API REST

Cada petición lleva una clave de API como bearer token. Las claves son para servidores. Si lo que quieres es conectar un asistente en vez de escribir código, usa el servidor MCP: se autentica en el navegador y no necesita ninguna clave.

Obtener una clave

Se crea desde los ajustes de tu cuenta. La clave completa se muestra una sola vez, al crearla, y después no se puede recuperar porque solo se guarda su hash. Si la pierdes, crea otra.

Authorization: Bearer ak_a1b2c3d4e5f6a7b8_<secret>

Las claves tienen la forma ak_<id>_<secreto>. La parte <id> es pública e identifica la clave en tus ajustes; la parte secreta es la que nunca debe acabar en un repositorio, en un log ni en un navegador.

Permisos

Una clave lleva permisos. write, publish y media implican read. write y publish son independientes: crear un borrador necesita write, y crear una publicación que de verdad se enviará necesita publish. Las claves creadas desde ajustes llevan los cuatro permisos; todavía no se pueden restringir ahí.

Una petición crea una publicación por cada cuenta de destino. Cada una es independiente, con su propia programación y su propio resultado; solo comparten un id de campaña.

curl https://antwork.io/api/v1/posts \
  -H "Authorization: Bearer $ANTWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "accounts": ["acc_linkedin", "acc_x"],
    "text": "Shipped the API today.",
    "scheduledFor": "2026-10-01T09:00:00Z"
  }'

Cuerpo de la petición

La respuesta es 202 Accepted, nunca 200. Nada se publica dentro de la petición: la publicación se encola y un worker la envía, así que la respuesta dice qué se ha aceptado, no qué se ha publicado.

{
  "object": "post_batch",
  "campaignId": "b3f1...",
  "posts": [
    {
      "object": "post_result",
      "id": "pQ7x...",
      "accountId": "acc_linkedin",
      "platform": "linkedin",
      "status": "accepted",
      "reason": null,
      "message": null
    },
    {
      "object": "post_result",
      "id": null,
      "accountId": "acc_x",
      "platform": "x",
      "status": "rejected",
      "reason": "text_too_long",
      "message": "@antwork: Text exceeds x character limit"
    }
  ]
}

Qué significa cada estado

• ›accepted — creada y programada (o guardada, si es un borrador). Consulta el id para ver qué pasa.
• ›rejected — rechazada antes de escribir nada. No existe; corrige reason y vuelve a enviar.
• ›failed — se creó pero no se pudo programar. Existe y no va a salir.

Programación

Omite scheduledFor para publicar de inmediato. Indica una hora ISO 8601 para programar, como máximo a 30 días. La cola que hay detrás no acepta tareas más lejanas, y el error indica la última hora que admite. Una hora en el pasado se rechaza con scheduled_for_in_past.

La llamada de creación devuelve ids; aquí es donde ves qué ha sido de ellos. Consulta en vez de esperar en la petición de creación, que responde mucho antes de que la plataforma conteste.

{
  "object": "post",
  "id": "pQ7x...",
  "workspaceId": "ws_...",
  "accountId": "acc_linkedin",
  "platform": "linkedin",
  "campaignId": "b3f1...",
  "status": "published",
  "text": "Shipped the API today.",
  "mediaUrls": [],
  "scheduledFor": "2026-10-01T09:00:00.000Z",
  "publishedAt": "2026-10-01T09:00:04.000Z",
  "publishedUrl": "https://www.linkedin.com/feed/update/...",
  "platformPostId": "urn:li:share:...",
  "error": null,
  "createdAt": "2026-09-22T10:00:00.000Z",
  "updatedAt": "2026-10-01T09:00:04.000Z"
}

Una vez ha salido, se rellenan publishedUrl y platformPostId. Si ha fallado, error.message dice qué contestó la plataforma y error.advice qué hacer al respecto.

Una publicación que no existe, es de otra persona o se ha eliminado responde 404 con post_not_found. Necesita el permiso read.

Estados de una publicación

• ›draft — guardada, sin programar. No se enviará.
• ›scheduled — esperando su hora, o enviándose ahora mismo.
• ›published — publicada en la plataforma. publishedUrl y platformPostId están rellenos.
• ›failed — no se publicó. error explica por qué.

Listar publicaciones

GET /api/v1/posts es la vía de recuperación: la única otra forma de llegar a una publicación es el id que devolvió la creación. De la más reciente a la más antigua, en todos tus espacios de trabajo. Filtro opcional status (uno de los cuatro de arriba), limit de 1 a 100 (por defecto 25) y cursor con el nextCursor de la página anterior. Un nextCursor nulo significa que no hay más.

curl "https://antwork.io/api/v1/posts?status=scheduled&limit=25" \
  -H "Authorization: Bearer $ANTWORK_API_KEY"

{ "object": "list", "posts": [ ... ], "nextCursor": "MTc5MDA3..." }

La primera llamada de cualquier integración, porque crear una publicación requiere ids de cuenta y no hay otra forma de conocerlos.

{
  "object": "list",
  "accounts": [
    {
      "object": "account",
      "id": "acc_linkedin",
      "workspaceId": "ws_...",
      "platform": "linkedin",
      "name": "Iker on LinkedIn",
      "handle": "iker",
      "accountType": "personal",
      "active": true,
      "tokenHealth": "healthy",
      "connectedAt": "2026-01-05T09:00:00.000Z"
    }
  ]
}

Filtra con ?workspaceId= o ?platform=.

La lista incluye todas las cuentas conectadas, también de plataformas en las que la API aún no puede publicar. Solo las cuentas de LinkedIn y X (Twitter) sirven en accounts al crear una publicación.

DELETE /api/v1/posts/{id} cancela una publicación programada o elimina un borrador. Una publicación ya publicada se borra de forma lógica para conservar su histórico de engagement, y en cualquier caso desaparece de todas las lecturas de esta API. Necesita el permiso write.

La publicación en la plataforma se queda como está salvo que lo pidas. ?deleteFromPlatform=true encola además el borrado de la publicación en vivo, que es irreversible y visible para otras personas. Quitar una publicación de Antwork y borrarla de LinkedIn son intenciones distintas, así que la API no lo adivina.

{
  "object": "post_deleted",
  "id": "pQ7x...",
  "softDeleted": true,
  "platformDeletionQueuedFor": ["linkedin"]
}

Todo lo específico de una plataforma va en options, indexado por plataforma y aplicado a todas las cuentas de esa plataforma en la petición. Solo las plataformas de esta tabla aceptan opciones por la API.

{
  "accounts": ["acc_x"],
  "text": "Shipped the API today.",
  "options": {
    "x": { "communityId": "1493446837214", "shareWithFollowers": true }
  }
}

Envía una cabecera Idempotency-Key en cada creación. Sin ella, un timeout de red seguido del reintento que tu cliente HTTP hace por su cuenta produce una segunda publicación.

La clave se recuerda 24 horas, asociada a tu cuenta y al cuerpo exacto de la petición.

• ›Misma clave, mismo cuerpo, ya terminada: se devuelve la respuesta original y no se crea nada nuevo.
• ›Misma clave mientras la primera petición sigue en curso: 409. Reintenta en un momento.
• ›Misma clave, cuerpo distinto: 422. Devolver la primera respuesta para otra petición sería peor que rechazarla.

Cada clave permite 10.000 peticiones al día y 120 por minuto. Los topes existen para frenar un bucle descontrolado, no para racionar el uso normal. Si te acercas a alguno, escríbenos en vez de sortearlo.

X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9812
X-RateLimit-Reset: 1790035200
Retry-After: 37

Todas las respuestas llevan el presupuesto actual, no solo las rechazadas, así que nunca hace falta agotar el límite para conocerlo. X-RateLimit-Reset es un timestamp Unix; Retry-After solo aparece en un 429 y va en segundos.

Todos los fallos tienen la misma forma. type es la clase sobre la que ramificar, code es el identificador estable del problema concreto y param nombra el campo culpable cuando lo hay. Trata message como texto para una persona leyendo un log: puede cambiar.

{
  "error": {
    "type": "invalid_request_error",
    "code": "scheduled_for_too_far",
    "message": "Posts can be scheduled at most 30 days ahead. The latest accepted time is 2026-10-22T10:00:00.000Z.",
    "param": "scheduledFor"
  }
}

Ramifica sobre code, nunca sobre message. Los códigos son parte del contrato; las frases no.

Códigos de error

Cuando no se acepta ninguna cuenta de una petición de creación, la respuesta es un 400 cuyo code es el motivo de rechazo de la primera cuenta (ver la tabla siguiente), con el array posts completo al lado.

Por qué se rechazó una cuenta

El reason de una entrada rejected o failed en la respuesta de creación.