antworkDOCS

Batch operations

Schedule, publish, change, read, unschedule or delete many posts in one request, each answered on its own.

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

One request, many posts

The one-post endpoints have a batch form that takes a list of post ids. It runs the same checks as the one-post endpoint for each post and answers each post alone, so a post that is missing or refused never stops the others. The call counts as one request against your rate limit. Use a batch instead of a loop: sending one request per post is how a client runs into rate_limit_exceeded.

Per call: POST /api/v1/posts/schedule schedules up to 25 posts, GET /api/v1/posts?ids= reads up to 25 and GET /api/v1/posts/comments?ids= the comments of up to 5, POST /api/v1/posts/publish sends up to 10, PUT /api/v1/posts/media sets the media of up to 25, and PATCH /api/v1/posts, POST /api/v1/posts/unschedule and /delete take up to 50. Past the limit the answer is a 400 too_many_posts, and its message gives the split to send instead. A repeated id counts once.

Scheduling several posts

POST /api/v1/posts/schedule schedules each post as POST /api/v1/posts/{id}/schedule does. Send schedules, one {postId, scheduledFor} per post, to give each its own time, or postIds with one scheduledFor for all of them. "next_slot" puts a post in its account's next free posting slot, one post after another so each takes its own. The answer is a post_result per post in the order you sent them, with scheduledFor on the accepted ones: 202 when any was accepted, and a 400 with the first reason when none was. Needs the publish scope. Send an 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", ... }
  ]
}

Posts that are already scheduled can be moved in the same call. The moves are applied in an order that never crosses a post still waiting, and each is checked against where the others end up, not where they are leaving, so shifting a whole run of posts by half an hour works in one request. When one move is refused, a later move that would land too close to it is rejected with batch_conflict, and its dependsOn names the post that stayed.

Publishing several posts

POST /api/v1/posts/publish with {"postIds": [...]} sends each post now, as POST /api/v1/posts/{id}/publish does, and retries a failed one. The answer is the campaign endpoints' batch: a post_result per post in the order you sent them, 202 when any was accepted, and a 400 with the first reason when none was. An id that is not a post on your account is rejected with post_not_found. Needs the publish scope. Send an Idempotency-Key: a retried request must not send the posts twice.

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", ... }
  ]
}

TikTok posts take the user's choices in tiktokSettings, keyed by post id, or as one answer when every TikTok post in the call is on the same TikTok account. One without them is rejected with tiktok_choices_needed and the tiktokChoices to ask from.

Reading several posts

GET /api/v1/posts?ids=a,b,c answers those posts in full, each as GET /api/v1/posts/{id} does, in the order you asked, and lists the ids it did not find in notFound. It is the way to poll a batch: one request for all of them. ids combines with no other parameter. Needs 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..."]
}

Reading comments on several posts

GET /api/v1/posts/comments?ids=a,b reads the comments on each published post as GET /api/v1/posts/{id}/comments does, live from its network, which is why it takes fewer posts than a plain read. limit is comments per post. Each row of posts is that post's comments, or a post_error with the code the one-post call would have answered (comments_unsupported, not_published). There is no cursor here: page one post with the one-post endpoint. Needs 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": "..." } }
  ]
}

Changing several posts

PATCH /api/v1/posts with {"updates": [{"postId": "...", ...}]} changes each post as PATCH /api/v1/posts/{id} does, each its own way: new text, hashtags, account, settings, a new time, or back to draft. Each row of posts is the post as it now stands, or a post_error with the code the one-post call would have answered. When an edit was saved and only its new time was refused, the row also carries the post. Needs write; an entry that moves a scheduled post or changes a published one also needs publish, and is refused on its own row without it. Send an 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", ... } }
  ]
}

Entries that move scheduled posts follow the same rule as /schedule: they are applied in an order that never crosses a post still waiting and held to the layout they end in, with batch_conflict and dependsOn for a move that would land too close to a post that stayed. A post may have one entry per call.

Setting the media of several posts

PUT /api/v1/posts/media with {"updates": [{"postId": "...", "media": [...]}]} sets each post's media as PUT /api/v1/posts/{id}/media does: the post's media becomes exactly that list (library media ids or URLs), in that order, and [] clears it. Use it to swap a video or an image across a run of posts in one request. Each row of posts is the post with its new media, or a post_error with the code the one-post call would have answered (media_not_found, media_not_in_library, post_already_published). A post may have one entry per call. Needs the media scope. Sending the same lists twice changes nothing, so no Idempotency-Key is needed.

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": "..." } }
  ]
}

Moving several posts back to draft

POST /api/v1/posts/unschedule with {"postIds": [...]} moves each scheduled post back to draft and cancels its queued publish. A post that was not scheduled is answered as it is, with unscheduled: false. Each row of posts is the post, or a post_error with the code a one-post call would have answered. Needs 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": "..." } }
  ]
}

Deleting several posts

POST /api/v1/posts/delete with {"postIds": [...]} deletes each post as DELETE /api/v1/posts/{id} does: a scheduled post is cancelled, a draft is removed, a published post keeps its history. It is a POST because the body of a DELETE request does not always arrive. Needs 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 also removes the live posts from their networks, for every post in the call. It cannot be undone, so it is off unless you send it.

When no post went through

PATCH /api/v1/posts, PUT /api/v1/posts/media, /unschedule, /delete and /comments answer 200 when at least one post was answered. When every post failed, the answer is the first post's error with its status (404 post_not_found, 409 post_already_published), and the rows are still in posts.

Something look wrong? Tell us which.