REST API

Every request carries an API key as a bearer token. Keys are for servers. If you are connecting an assistant rather than writing code, use the MCP server instead, which signs in through your browser and needs no key at all.

Getting a key

Create one from your account settings. The full key is shown once, at the moment it is created, and cannot be retrieved afterwards because only its hash is stored. Losing it means creating another.

Authorization: Bearer ak_a1b2c3d4e5f6a7b8_<secret>

Keys look like ak_<id>_<secret>. The <id> half is public and identifies the key in your settings; the secret half is the part that must never reach a repository, a log or a browser.

Scopes

A key carries scopes. write, publish and media each imply read. write and publish are separate rather than nested: creating a draft needs write, and creating a post that will actually go out needs publish. Keys created from settings carry all four scopes; there is no way to narrow a key there yet.

One request creates one post per target account. Each is an independent post with its own schedule and its own outcome; they share only a campaign id.

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"
  }'

Request body

The answer is 202 Accepted, never 200. Nothing publishes inside the request: a post is queued and a worker sends it, so the response tells you what was accepted rather than what was published.

{
  "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"
    }
  ]
}

What each target status means

• ›accepted — written, and scheduled (or saved, for a draft). Poll the id to see what happened.
• ›rejected — refused before anything was written. Nothing exists; fix reason and send again.
• ›failed — the post was created but could not be scheduled. It exists and will not go out.

Scheduling

Omit scheduledFor to publish immediately. Supply an ISO 8601 time to schedule, at most 30 days ahead. The queue behind this will not accept a task further out, and the error names the latest time it will take. A time in the past is refused with scheduled_for_in_past.

The create call returns ids; this is where you learn what became of them. Poll rather than waiting on the create request, which returns long before the platform has answered.

{
  "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"
}

Once it has gone out, publishedUrl and platformPostId are filled in. If it failed, error.message says what the platform said and error.advice says what to do about it.

A post that does not exist, belongs to someone else or has been deleted answers 404 with post_not_found. Needs the read scope.

Post statuses

• ›draft — saved, not scheduled. It will not go out.
• ›scheduled — waiting for its time, or being sent right now.
• ›published — live on the platform. publishedUrl and platformPostId are set.
• ›failed — did not go out. error says why.

Listing posts

GET /api/v1/posts is the recovery path: the only other way to reach a post is an id the create call returned once. Newest first, across every workspace you own. Optional status filter (one of the four above), limit from 1 to 100 (default 25), and cursor from the previous page's nextCursor. A null nextCursor means there are no more.

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

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

The first call any integration makes, because creating a post takes account ids and there is no other way to learn them.

{
  "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"
    }
  ]
}

Narrow with ?workspaceId= or ?platform=.

The list includes every connected account, including platforms the API cannot post to yet. Only LinkedIn and X (Twitter) accounts can be used in accounts when creating a post.

DELETE /api/v1/posts/{id} cancels a scheduled post or removes a draft. A published post is soft-deleted so its engagement history survives, and disappears from every read on this API either way. Needs the write scope.

The post on the platform is left alone unless you ask. ?deleteFromPlatform=true also queues deletion of the live post, which is irreversible and visible to other people. Removing a post from Antwork and deleting it from LinkedIn are different intentions, so the API does not guess.

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

Anything platform-specific goes in options, keyed by platform and applied to every account of that platform in the request. Only the platforms listed here accept options through the API.

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

Send an Idempotency-Key header on every create. Without one, a network timeout followed by the retry your HTTP client makes on its own produces a second post.

The key is remembered for 24 hours, scoped to your account and to the exact request body.

• ›Same key, same body, already finished — the original response is returned again and nothing new is created.
• ›Same key while the first request is still running — 409. Retry in a moment.
• ›Same key, different body — 422. Returning the first answer for a second request would be worse than refusing.

Each key allows 10,000 requests a day and 120 a minute. The ceilings exist to catch a runaway loop, not to ration normal use. If you are near either one, get in touch rather than working around it.

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

Every response carries the current budget, not just the ones that are refused, so you never have to exhaust the limit to discover it. X-RateLimit-Reset is a Unix timestamp; Retry-After appears only on a 429 and is in seconds.

Every failure has the same shape. type is the class to branch on, code is the stable identifier for the specific problem, and param names the offending field where there is one. Treat message as copy for a human reading a log; it can change.

{
  "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"
  }
}

Branch on code, never on message. The codes are part of the contract; the sentences are not.

Error codes

When no account in a create request is accepted, the answer is a 400 whose code is the first account's rejection reason (see the next table), with the full posts array beside it.

Why an account was rejected

The reason on a rejected or failed entry in a create response.