Cómo usar la API pública de Postoria

La API pública de Postoria te permite conectar herramientas externas, scripts y sistemas internos con Postoria.

Puedes utilizarla para conectar y reconectar cuentas sociales, listar tus espacios de trabajo y cuentas conectadas, subir recursos multimedia, crear y gestionar publicaciones y obtener analíticas actuales o agregadas.

La API pública está disponible en los planes Pro y Agency.

Antes de empezar

Estos son los aspectos principales que debes conocer antes de utilizar la API:

Necesitas un plan Pro o Agency activo.
Cada cuenta de Postoria puede tener una clave de API activa.
Las claves se aplican a toda la cuenta, no a un espacio de trabajo concreto.
Los endpoints específicos de un espacio requieren un workspace_id en la URL.
La API utiliza autenticación mediante token Bearer.
El límite es de 300 solicitudes cada 5 minutos por cuenta.
El procesamiento de recursos multimedia es asíncrono.
Las respuestas utilizan campos JSON en snake_case.
La versión v1 utiliza el prefijo de ruta /v1.

URL base

Utiliza esta URL base:

https://api.postoria.io/v1

La documentación de la API está disponible aquí: https://api.postoria.io/v1/docs/.

El documento OpenAPI está disponible aquí: https://api.postoria.io/v1/openapi.json.

Crea una clave de API

Abre Postoria.
Ve a Settings.
Busca la sección Public API.
Haz clic en Create API key.
Copia la clave y guárdala de forma segura.

Postoria solo muestra la clave completa una vez. Después de cerrar el cuadro de diálogo, únicamente verás su prefijo.

Si pierdes la clave, revócala y crea una nueva.

Autentica las solicitudes

Envía la clave en el encabezado Authorization:

Authorization: Bearer pst_live_your_api_key

Ejemplo:

curl https://api.postoria.io/v1/workspaces \
  -H "Authorization: Bearer pst_live_your_api_key"

Si la clave no está presente, no es válida o ha sido revocada, Postoria devuelve 401 invalid_api_key.

Formato de las respuestas

Las respuestas de un único recurso devuelven directamente el objeto.

Las respuestas de listas utilizan este formato:

{
  "data": [],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Cuando un endpoint de lista admite paginación, has_more indica si hay otra página disponible. Utiliza next para solicitarla directamente o envía el valor devuelto en next_cursor como parámetro de consulta cursor.

Las respuestas de error utilizan este formato:

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Límite de solicitudes

La API pública permite:

300 requests per 5 minutes per account

Si superas el límite, Postoria devuelve 429 rate_limit_exceeded con encabezados para indicar cuándo reintentar.

Ejemplo:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1770000000

Endpoints

La versión v1 de la API pública incluye estos endpoints:

GET    /v1/workspaces

GET    /v1/social-account-connection-options
POST   /v1/workspaces/{workspace_id}/social-account-connections
GET    /v1/workspaces/{workspace_id}/social-account-connections/{state}
POST   /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts
POST   /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect

GET    /v1/workspaces/{workspace_id}/social-accounts
PATCH  /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
GET    /v1/workspaces/{workspace_id}/queues

POST   /v1/workspaces/{workspace_id}/media/uploads
POST   /v1/workspaces/{workspace_id}/media/{media_id}/complete
POST   /v1/workspaces/{workspace_id}/media/imports
GET    /v1/workspaces/{workspace_id}/media/{media_id}

POST   /v1/workspaces/{workspace_id}/posts
GET    /v1/workspaces/{workspace_id}/posts
GET    /v1/workspaces/{workspace_id}/posts/{post_id}
DELETE /v1/workspaces/{workspace_id}/posts/{post_id}

GET    /v1/workspaces/{workspace_id}/analytics/posts
GET    /v1/workspaces/{workspace_id}/analytics/post-performance/summary

Lista los espacios de trabajo

Utiliza este endpoint para obtener los espacios disponibles en tu cuenta:

GET /v1/workspaces

Ejemplo de respuesta:

{
  "data": [
    {
      "id": 1,
      "name": "My Workspace",
      "timezone": "America/New_York"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Utiliza el id devuelto como workspace_id en los endpoints específicos del espacio.

Conecta o reconecta cuentas sociales

La API pública utiliza un flujo OAuth interactivo para conectar nuevas cuentas sociales o renovar la autorización de las existentes. Tu aplicación inicia una autorización, dirige al usuario a la URL del proveedor y consulta el estado de la conexión después de que el proveedor lo redirija de vuelta a Postoria.

El mismo flujo de autorización puede devolver tanto cuentas nuevas como existentes:

connectable_accounts contiene las cuentas del proveedor que no están conectadas en el espacio de trabajo especificado.
reconnectable_accounts contiene las cuentas existentes de ese espacio que pueden volver a autorizarse con la autorización OAuth obtenida.

Después de revisar estas listas, llama al endpoint de conexión con los PID del proveedor, al endpoint de reconexión con los ID de cuenta de Postoria o a ambos endpoints cuando corresponda.

Lista las opciones de conexión

Obtén las redes sociales y los métodos de autenticación disponibles actualmente mediante la API pública:

GET /v1/social-account-connection-options

Ejemplo de respuesta:

{
  "data": [
    {
      "network": "facebook",
      "auth_methods": [
        "facebook_login",
        "meta_business_portfolio"
      ]
    },
    {
      "network": "instagram",
      "auth_methods": [
        "instagram_login",
        "facebook_login",
        "meta_business_portfolio"
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

No utilices el ejemplo de respuesta como una lista completa fija. Toma este endpoint como fuente de referencia, ya que las opciones compatibles pueden cambiar.

La versión inicial admite estas opciones:

Red	Métodos de autenticación
`facebook`	`facebook_login`, `meta_business_portfolio`
`instagram`	`instagram_login`, `facebook_login`, `meta_business_portfolio`
`linkedin`	`linkedin_login`
`tumblr`	`tumblr_login`
`youtube`	`google_login`
`pinterest`	`pinterest_login`
`tiktok`	`tiktok_api_for_business`
`google_business_profile`	`google_login`
`threads`	`threads_login`

Inicia una autorización

Crea un estado de conexión para un espacio de trabajo:

POST /v1/workspaces/{workspace_id}/social-account-connections

Ejemplo de solicitud:

{
  "network": "instagram",
  "auth_method": "instagram_login"
}

Respuesta correcta (201 Created):

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "is_completed": false,
  "authorization_url": "https://www.instagram.com/oauth/authorize?...",
  "expires_at": "2026-09-07T11:25:28.222872Z"
}

Abre authorization_url en un navegador para que el usuario complete el flujo del proveedor. Después, el proveedor redirige el navegador a la URL de callback alojada por Postoria, que registra el resultado de OAuth asociado a state. Tu aplicación no necesita proporcionar una URL de retorno ni llamar a un endpoint de finalización independiente.

El estado caduca una hora después de crearse. Inicia una autorización nueva si ya ha pasado expires_at. Si el estado ha caducado o está asociado a otro espacio de trabajo o cuenta de Postoria, la API devuelve 404 social_account_connection_not_found.

Consulta el resultado de la autorización

Cuando el usuario haya completado el flujo del proveedor, consulta el estado de la conexión:

GET /v1/workspaces/{workspace_id}/social-account-connections/{state}

Puedes consultar periódicamente este endpoint mientras is_completed sea false. Este campo indica que Postoria todavía no ha recibido y almacenado el callback de OAuth; no significa que las cuentas ya se hayan conectado o reconectado.

Ejemplo de respuesta tras completar la autorización:

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "is_completed": true,
  "expires_at": "2026-09-07T11:25:28.222872Z",
  "network": "instagram",
  "auth_method": "instagram_login",
  "error": null,
  "connectable_accounts": [
    {
      "pid": "17841400000000001",
      "name": "Postoria Demo",
      "username": "postoria.demo",
      "description": "Demo account",
      "url": "https://www.instagram.com/postoria.demo/",
      "logo_url": "https://example.com/profile.jpg",
      "account_category": "profile"
    }
  ],
  "reconnectable_accounts": [
    {
      "account_id": 123,
      "pid": "17841400000000002",
      "name": "Postoria",
      "username": "postoria.app",
      "description": "Postoria",
      "url": "https://www.instagram.com/postoria.app/",
      "logo_url": "https://example.com/profile-2.jpg",
      "account_category": "profile"
    }
  ]
}

Si is_completed es true y error no es null, el proceso de autorización del proveedor ha fallado o el usuario lo ha rechazado. No llames a ninguno de los endpoints que modifican cuentas; muestra el error o inicia una autorización nueva.

Conecta cuentas nuevas

Selecciona uno o varios PID exactamente como aparecen en connectable_accounts:

POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts

Ejemplo de solicitud:

{
  "pids": [
    "17841400000000001"
  ]
}

La validación de la solicitud falla si un PID no está disponible mediante esta autorización o ya está conectado en el espacio de trabajo.

Reconecta cuentas existentes

Selecciona uno o varios ID de cuenta de Postoria exactamente como aparecen en reconnectable_accounts:

POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect

Ejemplo de solicitud:

{
  "account_ids": [123, 456]
}

Cada cuenta solicitada debe pertenecer al espacio de trabajo especificado y a la red seleccionada, y la autorización OAuth obtenida debe proporcionar acceso a ella. Si alguna cuenta solicitada no está disponible, la API devuelve 400 social_accounts_not_available antes de reconectar las cuentas seleccionadas.

Una cuenta existente puede reconectarse mediante cualquier método de autenticación admitido actualmente para su red; no tiene que coincidir con el método utilizado para la conexión original. Selecciona siempre el account_id devuelto en lugar de intentar determinar la correspondencia por tu cuenta.

Respuesta de las operaciones sobre cuentas

Tanto el endpoint de conexión como el de reconexión devuelven las cuentas de Postoria afectadas:

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "accounts": [
    {
      "id": 123,
      "name": "Postoria",
      "custom_name": "Channel 113",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app/",
      "metadata": {
        "channel_number": "113"
      }
    }
  ]
}

Lista las cuentas sociales

Utiliza este endpoint para obtener las cuentas conectadas de un espacio de trabajo:

GET /v1/workspaces/{workspace_id}/social-accounts

Ejemplo de respuesta:

{
  "data": [
    {
      "id": 123,
      "name": "Postoria",
      "custom_name": "Channel 113",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app",
      "metadata": {
        "channel_number": "113",
        "owner_account": "acme-media"
      }
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

name es el nombre de la cuenta recibido de la red social. custom_name es un nombre opcional configurado en Postoria. metadata es un objeto opcional que contiene claves y valores de texto controlados por tu integración. Las claves de los metadatos conservan el uso original de mayúsculas y minúsculas.

Utiliza los ID devueltos en social_account_ids al crear publicaciones. También puedes utilizar los metadatos para asociar cada cuenta conectada con un identificador estable de tu propio sistema.

Utiliza este endpoint para establecer o actualizar el nombre personalizado y los metadatos de una cuenta social conectada:

PATCH /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}

Ejemplo de solicitud:

{
  "custom_name": "Channel 113",
  "metadata": {
    "channel_number": "113",
    "owner_account": "acme-media",
    "group": "north-america"
  }
}

Ambos campos son opcionales, pero la solicitud debe incluir al menos uno. Los campos omitidos no se modifican.

Comportamiento importante:

Los espacios al principio y al final de custom_name se eliminan antes de almacenarlo; el nombre puede contener hasta 255 caracteres.
Establece custom_name en null o en una cadena vacía para dejar de utilizar el nombre personalizado en la interfaz de Postoria.
metadata debe ser un objeto JSON que contenga claves y valores de texto.
Los metadatos pueden contener hasta 50 entradas. Las claves pueden contener hasta 64 caracteres y los valores, hasta 1.024 caracteres.
Al enviar metadata, se reemplaza el objeto de metadatos completo; las claves individuales no se combinan con las existentes.
Establece metadata en null para borrar todos los metadatos o en {} para conservar un objeto de metadatos vacío.
Los nombres personalizados y los metadatos permanecen asociados a la cuenta social de Postoria cuando esta se reconecta o se vuelve a autorizar.

Respuesta correcta:

{
  "id": 123,
  "name": "Postoria",
  "custom_name": "Channel 113",
  "description": "postoria.app",
  "network": "instagram",
  "url": "https://www.instagram.com/postoria.app",
  "metadata": {
    "channel_number": "113",
    "owner_account": "acme-media",
    "group": "north-america"
  }
}

Si la cuenta social no existe en el espacio de trabajo especificado, la API devuelve 404 social_account_not_found.

Lista las colas

Utiliza este endpoint para obtener las colas de un espacio de trabajo:

GET /v1/workspaces/{workspace_id}/queues

Ejemplo de respuesta:

{
  "data": [
    {
      "id": 456,
      "name": "Morning posts",
      "is_paused": false
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Utiliza el ID de cola devuelto cuando crees una publicación con publish_mode establecido en queue.

Sube recursos multimedia

Hay dos formas de añadir recursos mediante la API:

Crear una URL de carga y subir el archivo por tu cuenta.
Importar el recurso desde una URL HTTPS pública.

Ambos métodos crean un objeto multimedia. Utiliza el endpoint de estado para comprobar cuándo está listo.

El elemento debe tener status igual a ready antes de poder incluirlo al crear una publicación.

Los tipos compatibles incluyen formatos habituales de imagen, vídeo y documentos, como JPEG, PNG, WebP, GIF, MP4, MOV y PDF.

Sube un archivo mediante una URL de carga

Primero, crea una carga:

POST /v1/workspaces/{workspace_id}/media/uploads

Solicitud:

{
  "name": "image.jpg",
  "content_type": "image/jpeg"
}

Ejemplo de respuesta:

{
  "id": 9001,
  "status": "waiting_for_upload",
  "upload": {
    "url": "https://temporary-upload-url.example"
  }
}

Sube los bytes del archivo a la upload.url devuelta mediante una solicitud HTTP PUT. Envía los bytes sin procesar como cuerpo de la solicitud y utiliza el mismo valor de content_type que al crear la carga.

Ejemplo:

curl -X PUT "https://temporary-upload-url.example" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@image.jpg"

La URL de carga es temporal. Si caduca antes de subir y completar el elemento, crea una nueva carga.

Después de subir el archivo, completa la carga:

POST /v1/workspaces/{workspace_id}/media/{media_id}/complete

Ejemplo de respuesta:

{
  "id": 9001,
  "status": "processing",
  "file_id": null,
  "error_code": null,
  "error_message": null
}

Postoria procesará el recurso en segundo plano.

Importa un recurso desde una URL

Utiliza este endpoint cuando el archivo ya esté disponible en una URL HTTPS pública:

POST /v1/workspaces/{workspace_id}/media/imports

Solicitud:

{
  "url": "https://example.com/video.mp4"
}

Ejemplo de respuesta:

{
  "id": 9002,
  "status": "processing",
  "file_id": null,
  "error_code": null,
  "error_message": null
}

Solo se admiten URL HTTPS públicas. No se admiten URL privadas o autenticadas, archivos locales ni rutas relativas.

Comprueba el estado de un recurso

Utiliza este endpoint para comprobar si un elemento está listo:

GET /v1/workspaces/{workspace_id}/media/{media_id}

Ejemplo de respuesta cuando está listo:

{
  "id": 9001,
  "status": "ready",
  "file_id": 701,
  "error_code": null,
  "error_message": null
}

Ejemplo de respuesta con error:

{
  "id": 9001,
  "status": "failed",
  "file_id": null,
  "error_code": "media_processing_failed",
  "error_message": "The file format is not supported."
}

Estados posibles:

waiting_for_upload
processing
ready
failed

Crea una publicación

Utiliza este endpoint para crear una publicación:

POST /v1/workspaces/{workspace_id}/posts

La API no crea borradores. La publicación se crea con uno de estos modos:

publish_now
schedule
queue

scheduled_time solo es obligatorio para schedule. queue_id solo es obligatorio para queue. No debes enviar ninguno de los dos campos con publish_now.

Todas las cuentas sociales seleccionadas deben admitir el tipo de contenido elegido; de lo contrario, se rechaza la solicitud.

Ejemplo de solicitud programada:

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Post caption",
  "first_comment": "More details in the first comment.",
  "comment_delay": 5,
  "is_ai_generated": true,
  "scheduled_time": "2026-06-01T10:00:00Z"
}

Ejemplo de respuesta:

{
  "id": 3001,
  "status": "scheduled",
  "date": "2026-06-01T10:00:00Z",
  "queue_id": null,
  "is_ai_generated": true,
  "results": [
    {
      "account_id": 123,
      "link_to_post": null,
      "error": null
    }
  ],
  "instagram": {
    "content": "image",
    "caption": "Post caption",
    "files": [
      {
        "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
      }
    ],
    "comment": "More details in the first comment.",
    "comment_delay": 5
  }
}

Las respuestas incluyen un objeto por cada red social activada, como facebook, instagram, linkedin, youtube o tiktok. Cada objeto de red contiene:

content: el tipo de contenido efectivo para esa red.
caption: el texto utilizado para esa red.
files: los archivos multimedia de esa red. Las URL son enlaces firmados temporales que pueden abrirse sin autenticación durante aproximadamente una hora. Un archivo también puede incluir thumbnail_url si hay una miniatura disponible.

Según la red y el tipo de contenido, el objeto también puede incluir comment y comment_delay, link u opciones de publicación específicas. comment_delay se expresa en minutos. Las publicaciones con enlaces y los primeros comentarios solo están disponibles donde la red y el tipo de contenido los admiten. Las Stories no admiten primeros comentarios.

Cuando están disponibles, los resultados de publicación se devuelven por cuenta en results. En publicaciones programadas o en cola, puede que no haya resultados hasta que se procese la publicación. Una publicación puede incluir resultados correctos y fallidos para distintas cuentas.

Divulgación de contenido generado por IA

Establece el campo de nivel superior is_ai_generated en true cuando la publicación deba llevar la indicación de contenido generado por IA de las redes sociales compatibles.

{
  "is_ai_generated": true
}

Postoria envía la indicación correspondiente cuando el destino y el tipo de contenido son compatibles:

Cuentas de Instagram
Publicaciones de vídeo de TikTok
Vídeos de YouTube
Publicaciones de X
Pines de Pinterest

El ajuste no se envía para publicaciones de fotos de TikTok. Los destinos y tipos de contenido no compatibles lo ignoran.

Campos de fecha y hora

Los campos de fecha y hora utilizan cadenas ISO 8601 en UTC.

Ejemplo:

"scheduled_time": "2026-06-01T10:00:00Z"

Utiliza UTC e incluye la Z final.

Si programas a partir de una hora local, conviértela a UTC antes de enviarla a la API.

Publica inmediatamente

Establece publish_mode en publish_now.

{
  "publish_mode": "publish_now",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Publishing from Postoria Public API"
}

Programa una publicación

Establece publish_mode en schedule e incluye scheduled_time.

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Scheduled from Postoria Public API",
  "scheduled_time": "2026-06-01T10:00:00Z"
}

scheduled_time debe ser una fecha futura.

Añade una publicación a una cola

Establece publish_mode en queue e incluye queue_id.

{
  "publish_mode": "queue",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Queued from Postoria Public API",
  "queue_id": 456
}

La cola debe pertenecer al mismo espacio de trabajo.

Tipos de contenido

Valores compatibles de content_type:

text
image
video
document
carousel
link
story
reel

Si no proporcionas content_type, Postoria intenta determinarlo a partir de los datos:

Varios elementos multimedia → carousel
Un elemento multimedia → el tipo correspondiente, como image, video o document
Una URL sin recursos multimedia → link
Solo texto → text

Siguen aplicándose las reglas específicas de cada red. Todas las cuentas seleccionadas deben admitir el tipo solicitado; de lo contrario, la API devuelve un error de validación y no crea la publicación.

Añade recursos multimedia a una publicación

Utiliza el array media para hacer referencia a elementos creados mediante los endpoints de carga o importación. Cada elemento debe tener status igual a ready.

{
  "media": [
    {
      "media_id": 9001
    }
  ]
}

En un vídeo puedes proporcionar opcionalmente una miniatura personalizada. thumbnail_media_id pertenece al media_id correspondiente y debe hacer referencia a una imagen lista.

{
  "media": [
    {
      "media_id": 9002,
      "thumbnail_media_id": 9003
    }
  ]
}

Publicaciones con enlaces

En publicaciones de tipo link, incluye link_url:

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "link",
  "caption": "Useful link",
  "link_url": "https://example.com/article",
  "scheduled_time": "2026-06-01T10:00:00Z"
}

Postoria importará la información del enlace al crear la publicación.

Primer comentario

Utiliza first_comment para añadir un primer comentario en las redes que lo admitan. Utiliza comment_delay para retrasarlo; el valor se expresa en minutos.

{
  "first_comment": "More details in the first comment."
}

Siguen aplicándose las reglas específicas de cada red. Los campos de respuesta del primer comentario solo se devuelven en las redes compatibles.

Opciones de Facebook

Utiliza el objeto facebook para las opciones específicas de Facebook:

{
  "facebook": {
    "location_id": "12345678901234567890",
    "also_publish_media_to_stories": true
  }
}

location_id es opcional y debe ser una cadena de entre 1 y 64 dígitos que represente un número mayor que cero. Identifica la página de Facebook correspondiente a la ubicación física que Meta debe asociar con la publicación. Envía el ID como una cadena JSON, no como un número, para evitar que los identificadores largos pierdan precisión.

Cuando also_publish_media_to_stories es true, Postoria crea primero la publicación normal y después publica cada archivo adjunto como una Story de Facebook independiente. La opción no tiene efecto cuando content_type es story o link.

Opciones de Instagram

Utiliza el objeto instagram para las opciones específicas de Instagram:

{
  "instagram": {
    "location_id": "12345678901234567890",
    "also_publish_media_to_stories": true,
    "collaborators": ["creator_one"],
    "publish_as_trial_reel": false,
    "auto_share_if_performs_well": false,
    "user_tags": [
      {
        "media_id": 9001,
        "username": "creator_one",
        "x": 0.5,
        "y": 0.5
      }
    ]
  }
}

location_id es opcional y debe tener el mismo formato que la opción de Facebook: una cadena de entre 1 y 64 dígitos que represente un número mayor que cero. Debe corresponder a una página de Facebook asociada a una ubicación física.

Cuando also_publish_media_to_stories es true, Postoria crea primero la publicación normal y después publica cada archivo adjunto como una Story de Instagram independiente. La opción no tiene efecto cuando content_type es story.

user_tags.media_id debe hacer referencia a un recurso adjunto a la misma publicación. En las respuestas, las etiquetas de usuario utilizan file_id en lugar de media_id.

Opciones de Pinterest

Utiliza el objeto pinterest para las opciones específicas de Pinterest:

{
  "pinterest": {
    "title": "Pin title",
    "website": "https://example.com/article",
    "alt_text": "A description of the image"
  }
}

website es la URL de destino del Pin.

Opciones de Google Business Profile

Utiliza el objeto google_business_profile para añadir un botón de acción:

{
  "google_business_profile": {
    "button_type": "LEARN_MORE",
    "button_url": "https://example.com"
  }
}

Los tipos compatibles son BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP y CALL. Se requiere una URL en todos salvo CALL.

Ajustes de republicación

Utiliza repost para configurar la republicación.

Ejemplo:

{
  "repost": {
    "frequency": "do_not_repeat",
    "until": null
  }
}

Si configuras una frecuencia, until debe ser una fecha y hora UTC futura cuando lo exijan los ajustes seleccionados.

Opciones de YouTube

Utiliza el objeto youtube al crear publicaciones para cuentas de YouTube.

Ejemplo:

{
  "youtube": {
    "title": "Video title",
    "visibility": "public",
    "category": "People & Blogs",
    "made_for_kids": false,
    "video_language": "en",
    "recording_date": "2026-06-01T00:00:00Z",
    "tags": ["tag1", "tag2"]
  }
}

Utiliza los campos de YouTube solo cuando al menos una cuenta seleccionada sea de YouTube.

Para consultar los valores compatibles, revisa la documentación de Bulk Upload: Cómo cargar publicaciones de forma masiva con un archivo CSV en Postoria.

Opciones de TikTok

Utiliza el objeto tiktok al crear publicaciones para cuentas de TikTok.

Ejemplo:

{
  "tiktok": {
    "who_can_watch": "public",
    "allow_comments": true,
    "allow_duet": false,
    "allow_stitch": false,
    "disclose_post_content": false,
    "your_brand": false,
    "branded_content": false,
    "photo_title": "Photo title",
    "auto_add_music": false
  }
}

Campos compatibles de TikTok:

who_can_watch: public, followers, friends o private
allow_comments: true o false
allow_duet: true o false
allow_stitch: true o false
disclose_post_content: true o false
your_brand: true o false
branded_content: true o false
photo_title: texto sin formato de hasta 90 caracteres
auto_add_music: true o false

Utiliza los campos de TikTok solo cuando al menos una cuenta seleccionada sea de TikTok.

Opciones de Tumblr

Utiliza el objeto tumblr para adjuntar etiquetas nativas de Tumblr separadas del texto:

{
  "caption": "Explore our latest indie game",
  "tumblr": {
    "tags": ["gaming", "indiegame", "steam", "hades2"]
  }
}

Postoria admite hasta 30 etiquetas de Tumblr. Elimina el espacio alrededor y un # inicial, ignora valores vacíos y elimina duplicados sin distinguir mayúsculas y minúsculas. Un elemento del array no puede contener una coma ni comillas dobles. Utiliza estas opciones solo cuando al menos una cuenta seleccionada sea de Tumblr.

Lista publicaciones

Utiliza este endpoint para listar las publicaciones de un espacio:

GET /v1/workspaces/{workspace_id}/posts

Parámetros de consulta opcionales:

account_ids: ID de cuentas sociales. Repite el parámetro o utiliza valores separados por comas.
queue_id: ID de cola.
status: uno de draft, scheduled, in_progress, posted o queued.
networks: uno o varios valores de red, como instagram, facebook, linkedin, youtube o tiktok.
date_from: fecha y hora programada igual o posterior a este valor UTC.
date_to: fecha y hora programada anterior a este valor UTC.
limit: número de publicaciones que se devolverán. El valor predeterminado es 25 y el máximo es 100.
cursor: cursor de paginación devuelto por la página anterior.

account_ids y queue_id deben pertenecer al espacio especificado.

Ejemplo de solicitud:

curl "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25" \
  -H "Authorization: Bearer pst_live_your_api_key"

Ejemplo de respuesta:

{
  "data": [
    {
      "id": 3001,
      "status": "scheduled",
      "date": "2026-06-01T10:00:00Z",
      "queue_id": null,
      "is_ai_generated": true,
      "results": [
        {
          "account_id": 123,
          "link_to_post": null,
          "error": null
        }
      ],
      "instagram": {
        "caption": "Scheduled post caption",
        "files": [
          {
            "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
          }
        ]
      }
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0",
    "next": "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0"
  }
}

Para solicitar la página siguiente, llama directamente a next o vuelve a enviar next_cursor como cursor:

GET /v1/workspaces/{workspace_id}/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0

Comprueba el estado de una publicación

Utiliza este endpoint para consultar el estado:

GET /v1/workspaces/{workspace_id}/posts/{post_id}

date es la hora de publicación programada. Puede ser null en publicaciones en cola o inmediatas.

Ejemplo de respuesta:

{
  "id": 3001,
  "status": "posted",
  "date": "2026-06-01T10:00:00Z",
  "queue_id": null,
  "is_ai_generated": true,
  "results": [
    {
      "account_id": 123,
      "link_to_post": "https://www.instagram.com/p/example",
      "error": null
    }
  ],
  "instagram": {
    "caption": "Published post caption",
    "files": [
      {
        "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
      }
    ]
  }
}

Estados posibles:

draft
scheduled
in_progress
posted
queued

Significado de los elementos de resultado:

link_to_post contiene un valor cuando la publicación se ha publicado correctamente y hay un enlace público disponible.
error contiene un valor cuando ha fallado la publicación para esa cuenta.
Tanto link_to_post como error pueden ser null antes de que se publique.

Elimina una publicación

Utiliza este endpoint para eliminarla:

DELETE /v1/workspaces/{workspace_id}/posts/{post_id}

Respuesta correcta:

204 No Content

La publicación debe pertenecer al espacio especificado.

Al eliminarla, desaparece de Postoria. Esto no elimina contenido que ya se haya publicado en las redes sociales. Si la publicación ya ha comenzado, eliminarla de Postoria no detiene el proceso. Los resultados de las cuentas se eliminan junto con la publicación y no pueden recuperarse después.

Obtén analíticas de publicaciones concretas

Utiliza este endpoint para obtener las analíticas disponibles más recientes de entre uno y 100 ID de publicaciones de Postoria:

GET /v1/workspaces/{workspace_id}/analytics/posts?post_ids=3001&post_ids=3002

Repite post_ids para cada publicación. Los ID deben ser números enteros positivos. Se aceptan duplicados y se tratan como un único ID.

Todas las publicaciones solicitadas deben pertenecer al espacio. Si falta alguna o pertenece a otro espacio, toda la solicitud falla con 404 post_not_found; la respuesta no identifica qué ID ha fallado.

La respuesta contiene una fila por cada publicación en una cuenta social asociada a las publicaciones solicitadas. Las métricas se representan como pares nombre/valor porque su disponibilidad varía según la red y puede cambiar con el tiempo:

{
  "data": [
    {
      "post_id": 3001,
      "social_account_id": 123,
      "network": "tiktok",
      "content_type": "video",
      "published_at": "2026-08-01T10:00:00Z",
      "analytics_refreshed_at": "2026-08-25T12:34:56Z",
      "metrics": [
        { "name": "views", "value": 1250 },
        { "name": "likes", "value": 84 }
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Las métricas no disponibles se omiten. Si se sabe que el valor de una métrica es cero, se devuelve cero. analytics_refreshed_at indica la fecha y hora, en formato ISO 8601 y UTC, de la última vez que Postoria obtuvo correctamente las analíticas de la publicación de la red social. Si la publicación existe pero sus analíticas aún no están disponibles, analytics_refreshed_at es null y metrics es un array vacío.

Los valores de red utilizan identificadores canónicos, como linkedin, youtube, tiktok y google_business_profile.

Las métricas de YouTube utilizan nombres diferenciados con el prefijo youtube_. Algunos ejemplos son youtube_views, youtube_engaged_views, youtube_likes, youtube_dislikes, youtube_estimated_minutes_watched, youtube_average_view_duration y youtube_subscribers_gained. El endpoint puede devolver tanto métricas aditivas como promedios o tasas no aditivas.

Obtén un resumen agregado del rendimiento

Utiliza este endpoint para agregar las métricas disponibles más recientes del contenido publicado durante un intervalo UTC:

GET /v1/workspaces/{workspace_id}/analytics/post-performance/summary?published_from=2026-08-01T00:00:00Z&published_to=2026-09-01T00:00:00Z&granularity=day&group_by=network

Parámetros de consulta obligatorios:

published_from: marca de tiempo UTC ISO 8601 inclusiva con Z o +00:00.
published_to: marca de tiempo UTC ISO 8601 exclusiva con Z o +00:00.

El intervalo debe ser superior a cero y no puede superar 366 días.

Parámetros opcionales:

granularity: hour, day, month o year. Omítelo para no devolver intervalos temporales de publicación.
group_by: network, content_type o social_account. Omítelo para no utilizar una dimensión adicional de agrupación.

granularity y group_by son independientes. Por ejemplo, puedes agrupar por red sin intervalos de tiempo, utilizar intervalos diarios sin agrupar por una dimensión, combinar ambos u omitirlos para obtener una sola fila total.

Cuando está presente granularity, los intervalos utilizan la zona horaria del espacio. La respuesta incluye esa zona IANA y un published_period por fila. start y end son instantes UTC, end es exclusivo y key es la etiqueta correspondiente en la hora local del espacio.

{
  "data": [
    {
      "published_period": {
        "start": "2026-08-01T04:00:00Z",
        "end": "2026-08-02T04:00:00Z",
        "key": "2026-08-01"
      },
      "network": "linkedin",
      "post_count": 3,
      "metrics": [
        { "name": "views", "value": 4200 },
        { "name": "comments", "value": 17 }
      ]
    }
  ],
  "timezone": "America/New_York"
}

Si se omite granularity, también se omiten published_period y el campo superior timezone. Si se omite group_by, no se devuelve ningún campo de agrupación. En caso contrario, cada fila contiene exactamente uno de estos campos: network, content_type o social_account_id.

El resumen agrupa las publicaciones según el momento en que salieron. Suma sus métricas disponibles más recientes; no muestra cuándo se produjeron las visualizaciones, reacciones u otras interacciones. Los totales cero y las métricas no disponibles se omiten. Las métricas no aditivas, como video_skip_rate, video_average_watch_time_milliseconds, los promedios de YouTube y las tasas de YouTube, no se incluyen porque no se pueden sumar correctamente.

Errores habituales

Clave de API no válida

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Plan obligatorio

{
  "error": {
    "code": "public_api_plan_required",
    "message": "Public API access is available on Pro and Agency plans.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Error de validación

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": "content_type",
    "details": {
      "reason": "The selected social account does not support this content type."
    },
    "request_id": "req_abc123"
  }
}

Espacio de trabajo no encontrado

{
  "error": {
    "code": "workspace_not_found",
    "message": "The requested workspace was not found.",
    "param": "workspace_id",
    "details": null,
    "request_id": "req_abc123"
  }
}

Buenas prácticas

Guarda la clave de API de forma segura.
No expongas la clave en código frontend.
Sube o importa primero los recursos y espera hasta que su estado sea ready.
Utiliza GET /posts/{post_id} para comprobar el estado después de crear una publicación.
Trata los nombres de métricas como extensibles en lugar de codificar un conjunto fijo.
Utiliza UTC en los filtros del resumen; al usar granularity, interpreta las claves de intervalo según la zona horaria devuelta del espacio.
Gestiona los errores de validación y muestra a tus usuarios el mensaje recibido.
Reintenta únicamente después de respetar los encabezados de límite de solicitudes.
Revoca la clave inmediatamente si crees que se ha expuesto.

Cómo usar la API pública de Postoria

Antes de empezar

URL base

Crea una clave de API

Autentica las solicitudes

Formato de las respuestas

Límite de solicitudes

Endpoints

Lista los espacios de trabajo

Conecta o reconecta cuentas sociales

Lista las opciones de conexión

Inicia una autorización

Consulta el resultado de la autorización

Conecta cuentas nuevas

Reconecta cuentas existentes

Respuesta de las operaciones sobre cuentas

Lista las cuentas sociales

Actualiza una cuenta social

Lista las colas

Sube recursos multimedia

Sube un archivo mediante una URL de carga

Importa un recurso desde una URL

Comprueba el estado de un recurso

Crea una publicación

Divulgación de contenido generado por IA

Campos de fecha y hora

Publica inmediatamente

Programa una publicación

Añade una publicación a una cola

Tipos de contenido

Añade recursos multimedia a una publicación

Publicaciones con enlaces

Primer comentario

Opciones de Facebook

Opciones de Instagram

Opciones de Pinterest

Opciones de Google Business Profile

Ajustes de republicación

Opciones de YouTube

Opciones de TikTok

Opciones de Tumblr

Lista publicaciones

Comprueba el estado de una publicación

Elimina una publicación

Obtén analíticas de publicaciones concretas

Obtén un resumen agregado del rendimiento

Errores habituales

Clave de API no válida

Plan obligatorio

Error de validación

Espacio de trabajo no encontrado

Buenas prácticas