antworkDOCS

Operaciones por lotes

Programa, publica, cambia, lee, desprograma o elimina muchas publicaciones en una sola petición, cada una con su propia respuesta.

POSThttps://antwork.io/api/v1/posts/schedulePermisopublish

Una petición, muchas publicaciones

Los endpoints de una publicación tienen una forma por lotes que recibe una lista de ids. Aplica a cada publicación las mismas comprobaciones que el endpoint de una sola y responde por cada una, así que una publicación que falta o que se rechaza nunca frena a las demás. La llamada cuenta como una sola petición en tu límite de frecuencia. Usa un lote en lugar de un bucle: enviar una petición por publicación es como un cliente acaba en rate_limit_exceeded.

Por llamada: POST /api/v1/posts/schedule programa hasta 25 publicaciones, GET /api/v1/posts?ids= lee hasta 25 y GET /api/v1/posts/comments?ids= los comentarios de hasta 5, POST /api/v1/posts/publish envía hasta 10, PUT /api/v1/posts/media cambia los medios de hasta 25, y PATCH /api/v1/posts, POST /api/v1/posts/unschedule y /delete aceptan hasta 50. Por encima del límite la respuesta es un 400 too_many_posts, y su mensaje indica cómo repartirlas. Un id repetido cuenta una vez.

Programar varias publicaciones

POST /api/v1/posts/schedule programa cada publicación como POST /api/v1/posts/{id}/schedule. Envía schedules, un {postId, scheduledFor} por publicación, para dar a cada una su hora, o postIds con un solo scheduledFor para todas. "next_slot" pone una publicación en el siguiente hueco libre de su cuenta, una tras otra para que cada una ocupe el suyo. La respuesta es un post_result por publicación en el orden en que las enviaste, con scheduledFor en las aceptadas: 202 cuando se aceptó alguna y un 400 con el primer motivo cuando no se aceptó ninguna. Necesita el permiso publish. Envía un Idempotency-Key.

curl -X POST https://antwork.io/api/v1/posts/schedule \
  -H "Authorization: Bearer $ANTWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "schedules": [
      {
        "postId": "pQ7x...",
        "scheduledFor": "2026-12-01T09:00:00Z"
      },
      {
        "postId": "pR2k...",
        "scheduledFor": "2026-12-02T09:00:00Z"
      }
    ]
  }'
202 Accepted
{
  "object": "post_batch",
  "campaignId": null,
  "posts": [
    { "object": "post_result", "id": "pQ7x...", "status": "accepted", "reason": null,
      "scheduledFor": "2026-12-01T09:00:00.000Z", ... },
    { "object": "post_result", "id": "pR2k...", "status": "rejected", "reason": "daily_cap_reached", ... }
  ]
}

Las publicaciones que ya están programadas se pueden mover en la misma llamada. Los cambios se aplican en un orden que nunca cruza una publicación que sigue esperando, y cada uno se comprueba contra donde acaban las demás, no contra donde estaban, así que desplazar media hora toda una serie de publicaciones funciona en una sola petición. Cuando un cambio se rechaza, otro posterior que quedaría demasiado cerca se rechaza con batch_conflict, y su dependsOn nombra la publicación que no se movió.

Publicar varias publicaciones

POST /api/v1/posts/publish con {"postIds": [...]} envía cada publicación ahora, como POST /api/v1/posts/{id}/publish, y reintenta una fallida. La respuesta es el lote de los endpoints de campaña: un post_result por publicación en el orden en que las enviaste, 202 cuando se aceptó alguna y un 400 con el primer motivo cuando no se aceptó ninguna. Un id que no es una publicación de tu cuenta se rechaza con post_not_found. Necesita el permiso publish. Envía un Idempotency-Key: una petición reintentada no debe enviar las publicaciones dos veces.

curl -X POST https://antwork.io/api/v1/posts/publish \
  -H "Authorization: Bearer $ANTWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "postIds": [
      "pQ7x...",
      "pR2k..."
    ]
  }'
202 Accepted
{
  "object": "post_batch",
  "campaignId": null,
  "posts": [
    { "object": "post_result", "id": "pQ7x...", "platform": "linkedin", "status": "accepted", "reason": null, ... },
    { "object": "post_result", "id": "pR2k...", "platform": "x", "status": "rejected", "reason": "text_too_long", ... }
  ]
}

Las publicaciones de TikTok reciben las elecciones del usuario en tiktokSettings, por id de publicación, o como una sola respuesta cuando todas las de TikTok de la llamada están en la misma cuenta de TikTok. Una sin ellas se rechaza con tiktok_choices_needed y los tiktokChoices que hay que preguntar.

Leer varias publicaciones

GET /api/v1/posts?ids=a,b,c responde esas publicaciones completas, cada una como GET /api/v1/posts/{id}, en el orden en que las pediste, y lista en notFound los ids que no encontró. Es la forma de consultar un lote: una petición para todas. ids no se combina con ningún otro parámetro. Necesita read.

curl "https://antwork.io/api/v1/posts?ids=pQ7x...,pR2k..." \
  -H "Authorization: Bearer $ANTWORK_API_KEY"
200 OK
{
  "object": "list",
  "posts": [
    { "object": "post", "id": "pQ7x...", "status": "published", "publishedUrl": "https://...", ... }
  ],
  "nextCursor": null,
  "notFound": ["pR2k..."]
}

Leer los comentarios de varias publicaciones

GET /api/v1/posts/comments?ids=a,b lee los comentarios de cada publicación publicada como GET /api/v1/posts/{id}/comments, en directo desde su red, y por eso acepta menos publicaciones que una lectura normal. limit son comentarios por publicación. Cada fila de posts son los comentarios de esa publicación, o un post_error con el código que habría respondido la llamada de una sola (comments_unsupported, not_published). Aquí no hay cursor: pagina una publicación con el endpoint de una sola. Necesita read.

curl "https://antwork.io/api/v1/posts/comments?ids=pQ7x...,pR2k..." \
  -H "Authorization: Bearer $ANTWORK_API_KEY"
200 OK
{
  "object": "post_comments_batch",
  "readCount": 1,
  "failedCount": 1,
  "posts": [
    { "postId": "pQ7x...", "platform": "x", "comments": [ { "id": "...", "text": "..." } ], "nextCursor": null, ... },
    { "object": "post_error", "id": "pR2k...",
      "error": { "type": "invalid_request_error", "code": "comments_unsupported", "message": "..." } }
  ]
}

Cambiar varias publicaciones

PATCH /api/v1/posts con {"updates": [{"postId": "...", ...}]} cambia cada publicación como PATCH /api/v1/posts/{id}, cada una a su manera: texto nuevo, hashtags, cuenta, ajustes, otra hora o de vuelta a borrador. Cada fila de posts es la publicación tal como queda, o un post_error con el código que habría respondido la llamada de una sola publicación. Cuando el cambio se guardó y solo se rechazó su nueva hora, la fila lleva también el post. Necesita write; una entrada que mueve una publicación programada o cambia una ya publicada necesita además publish, y sin él se rechaza en su propia fila. Envía un Idempotency-Key.

curl -X PATCH https://antwork.io/api/v1/posts \
  -H "Authorization: Bearer $ANTWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "updates": [
      {
        "postId": "pQ7x...",
        "text": "New copy for this one."
      },
      {
        "postId": "pR2k...",
        "scheduledFor": "2026-12-02T09:30:00Z"
      }
    ]
  }'
200 OK
{
  "object": "post_update_batch",
  "updatedCount": 1,
  "failedCount": 1,
  "posts": [
    { "object": "post", "id": "pQ7x...", "status": "draft", ... },
    { "object": "post_error", "id": "pR2k...",
      "error": { "type": "invalid_request_error", "code": "daily_cap_reached", "message": "..." },
      "post": { "object": "post", "id": "pR2k...", "status": "scheduled", ... } }
  ]
}

Las entradas que mueven publicaciones programadas siguen la misma regla que /schedule: se aplican en un orden que nunca cruza una publicación que sigue esperando y se comprueban contra la disposición final, con batch_conflict y dependsOn para un cambio que quedaría demasiado cerca de una publicación que no se movió. Una publicación puede tener una sola entrada por llamada.

Cambiar los medios de varias publicaciones

PUT /api/v1/posts/media con {"updates": [{"postId": "...", "media": [...]}]} deja los medios de cada publicación como PUT /api/v1/posts/{id}/media: exactamente en esa lista (ids de la biblioteca o URLs) y en ese orden, y [] los vacía. Sirve para cambiar un vídeo o una imagen en una serie de publicaciones con una sola petición. Cada fila de posts es la publicación con sus medios nuevos, o un post_error con el código que habría respondido la llamada de una sola publicación (media_not_found, media_not_in_library, post_already_published). Una publicación puede tener una sola entrada por llamada. Necesita el permiso media. Enviar las mismas listas dos veces no cambia nada, así que no hace falta Idempotency-Key.

curl -X PUT https://antwork.io/api/v1/posts/media \
  -H "Authorization: Bearer $ANTWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "postId": "pQ7x...",
        "media": [
          "med_8sKq..."
        ]
      },
      {
        "postId": "pR2k...",
        "media": []
      }
    ]
  }'
200 OK
{
  "object": "post_media_batch",
  "updatedCount": 1,
  "failedCount": 1,
  "posts": [
    { "object": "post", "id": "pQ7x...", "status": "scheduled", "readiness": { ... }, ... },
    { "object": "post_error", "id": "pR2k...",
      "error": { "type": "invalid_request_error", "code": "post_already_published", "message": "..." } }
  ]
}

Devolver varias publicaciones a borrador

POST /api/v1/posts/unschedule con {"postIds": [...]} devuelve cada publicación programada a borrador y cancela su envío en cola. Una publicación que no estaba programada se responde tal cual, con unscheduled: false. Cada fila de posts es la publicación, o un post_error con el código que habría respondido una llamada de una sola publicación. Necesita write.

curl -X POST https://antwork.io/api/v1/posts/unschedule \
  -H "Authorization: Bearer $ANTWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postIds": [
      "pQ7x...",
      "pR2k..."
    ]
  }'
200 OK
{
  "object": "post_unschedule_batch",
  "unscheduledCount": 1,
  "failedCount": 1,
  "posts": [
    { "object": "post", "id": "pQ7x...", "status": "draft", "unscheduled": true, ... },
    { "object": "post_error", "id": "pR2k...",
      "error": { "type": "invalid_request_error", "code": "post_already_published", "message": "..." } }
  ]
}

Eliminar varias publicaciones

POST /api/v1/posts/delete con {"postIds": [...]} elimina cada publicación como DELETE /api/v1/posts/{id}: una programada se cancela, un borrador se elimina y una publicada conserva su historial. Es un POST porque el cuerpo de una petición DELETE no siempre llega. Necesita write.

curl -X POST https://antwork.io/api/v1/posts/delete \
  -H "Authorization: Bearer $ANTWORK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "postIds": [
      "pQ7x...",
      "pR2k..."
    ]
  }'
200 OK
{
  "object": "post_delete_batch",
  "deletedCount": 2,
  "failedCount": 0,
  "posts": [
    { "object": "post_deleted", "id": "pQ7x...", "softDeleted": false, ... },
    { "object": "post_deleted", "id": "pR2k...", "softDeleted": true, ... }
  ]
}
"deleteFromPlatform": true también borra las publicaciones en sus redes, para todas las de la llamada. No se puede deshacer, así que está desactivado salvo que lo envíes.

Cuando ninguna publicación sale adelante

PATCH /api/v1/posts, PUT /api/v1/posts/media, /unschedule, /delete y /comments responden 200 cuando se respondió al menos una publicación. Cuando todas fallaron, la respuesta es el error de la primera con su estado (404 post_not_found, 409 post_already_published), y las filas siguen en posts.

¿Algo no cuadra? Dinos cuál.