00d 00:00:00 · Black Friday — 30% off 00d 00:00:00 · Black Friday — 30% off 00d 00:00:00 · Black Friday — 30% off 00d 00:00:00 · Black Friday — 30% off
API

Your marketing agent, one request away.

A REST API with a published OpenAPI spec. Create and schedule posts, ask for drafts and whole campaigns, and connect channels, all from your own product.

POST/v1/postsv1
{
  "brand": "br_7f3c",
  "text": "Launch day",
  "channels": ["instagram", "linkedin"],
  "at": "2026-11-20T09:00:00Z"
}
201 Created{ "id": "post_8f2k" }
200OK 202queued SuperAgent mascot head
One call

You send it once. It reaches every channel.

Your code sends a caption, the media and the channels it wants. We schedule it, hand it to each network, and keep the status of every copy up to date.

Your app
POST /v1/posts
{
  "text", "channels",
  "at"
}
201 Created { "id": "post_8f2k" }
SuperAgent Schedules, publishes, tracks each copy
Social networks
IgfinXTtThPYtGTg
Blogs and sites
WWf

WordPress and Webflow take articles. A webhook channel takes anything else, including a CMS we do not support yet.

Endpoint explorer

Every endpoint, on one wall.

Pick one to see what it does and what it takes. This is the shape of the v1 surface, and the full list ships with the spec.

// Account and brands
// Channels
// Studio designs
// Posts
// AI and campaigns
// Workflows
POST /v1/posts

Creates a post. Send at to schedule it; leave it out to save a draft.

Takes
brand, text, channels, at, status
Returns

→ 201 and the post id

Full reference
Auth in three lines

A key, a header, a first call.

No OAuth dance for your server. One key in one header, and you are talking to the API.

Good to know
  • A key is scoped to one brand. It cannot read another brand's posts.
  • The key is shown once. Copy it the moment you create it.
  • Deleting a key stops it at once. Create the replacement first, then delete the old one.
  1. 01
    Create a key

    Settings, then API. Name it after where it runs, so you know what breaks if you delete it.

    Settings → API → Create key
  2. 02
    Send it as a bearer token

    Every request carries it in the Authorization header. Keep it on your server, never in a browser.

    Authorization: Bearer sk_live_••••a91f
  3. 03
    Call /v1/brands

    You get back the brands the key can reach. Take a brandId; every other call needs one.

    $ curl "$API/v1/brands" \ -H "Authorization: Bearer $KEY"

That is the whole handshake. No token exchange, no refresh loop.

Settings, then API also shows a chart of your requests over the last hour, day or 30 days.

Your language

Same request, whatever you write.

The docs show every call in curl, JavaScript, Node, Python and PHP. The spec is OpenAPI 3.1, so a typed client, Postman or Insomnia all read it as-is.

  • Generate a client straight from the spec
  • Try any call from the docs, in the browser
  • Shapes stay in step with the API

A wrong field comes back as a 400 that names the field and the call, with a request id you can quote.

schedule.sh
curl -X POST "$API/v1/posts" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brand": "br_7f3c",
    "text": "Doors open at 9 on Saturday",
    "channels": ["instagram", "linkedin"],
    "at": "2026-11-20T08:00:00Z"
  }'
201 Created{ "id": "post_8f2k", "status": "scheduled" }
200 OK·201 Post created·202 Campaign queued·204 Deleted·400 Invalid request·401 Key revoked·404 No such brand·429 Over 60 a minute, slow down·500 Unknown error·200 OK·201 Post created·202 Campaign queued·204 Deleted·400 Invalid request·401 Key revoked·404 No such brand·429 Over 60 a minute, slow down·500 Unknown error·
Async by default

AI work never holds up your request.

Ask for a draft or a campaign and the answer comes straight back, with the job generating. The posts fill in behind it, and you read them back whenever you like.

POST /v1/campaigns · 202
$ 202 in a blink queued: true · campaignId: cmp_4f8
202 in a blink

POST /v1/campaigns answers at once with a campaignId and queued: true. GET /v1/campaigns/{id} shows how far it has got.

Filter by status

Ask GET /v1/posts for any status, from generating to posted, and get only those back.

Approval aware

A post waiting on a teammate or a client says so in its status, so your code never assumes it went out.

Post statuses you can filter on
  • GENERATINGThe AI is still writing or drawing.
  • DRAFTSaved, not scheduled.
  • PENDING_APPROVALWaiting on a teammate.
  • PENDING_CLIENTWaiting on the client.
  • SCHEDULEDQueued for its time.
  • POSTEDLive on the network.
  • ERRORPublishing failed, with the reason on the post.
Your URL as a channel

Posts can land on your own URL too.

Add a webhook channel and we POST each post to your endpoint as JSON when it publishes, and again when it is deleted. Your code decides what publishing means: a CMS entry, a database row, a message on a queue.

POSTpost.published The post, its caption, image and options.
{
  "event": "post.published",
  "post": {
    "id": "clx…",
    "title": "…",
    "caption": "…",
    "image": "https://…",
    "options": { "slug": "…" }
  }
}
POSTpost.deleted The id you gave back when it published.
{
  "event": "post.deleted",
  "id": "9f2c1a",
  "post": { … }
}
What your endpoint sends back
  1. 1
    A 2xx status

    Anything else is recorded as a failed publish, with your reason on the post.

  2. 2
    An id of your own

    Whatever you created. Deletes use the same id, so you can find it again.

  3. 3
    A url

    Where it went live. It becomes the View post link on the calendar.

Answer within 30 seconds. Acknowledge first, do the slow work after.

Add it in the app: Channels → Connect channel → Webhook.

Build it with us

Things people build in an afternoon.

Ideas, not case studies. Each one uses only the endpoints on this page.

recipe_01

A share-to-socials button

Your app already has the text and the image. One call sends them to the channels your customer picked.

1GET/v1/channels2POST/v1/posts
recipe_02

Drafts from product events

A feature ships, your backend asks for a caption in the brand voice. Someone checks the draft before it goes.

1POST/v1/generate/text2GET/v1/posts/{id}
recipe_03

A campaign in one click

Put a launch button in your admin. It queues a week of posts, and you read the campaign back with its posts.

1POST/v1/campaigns2GET/v1/campaigns/{id}
recipe_04

Brand voice from your own tools

Keep tone, keywords and hashtags in your CMS, and sync them to the brand so every draft starts from them.

1GET/v1/brands/{brandId}2PATCH/v1/brands/{brandId}
recipe_05

Articles to your blog

Connect WordPress or Webflow as a channel, and a post can land on the blog as well as the socials.

1GET/v1/channels/connection-url2POST/v1/posts
recipe_06

Automations on a switch

Pause every workflow from your ops dashboard during an incident, and turn them back on after.

1GET/v1/workflows2POST/v1/workflows/{id}/toggle
Under the hood

The same engine as the app.

Posts you create in code sit in the calendar next to everything else, get the same approvals, and publish through the same workers. There is no second-class path and no separate queue.

Read the API reference
Same calendarSame AISame channelsSame credits
What the API covers today

Posts, AI drafts, your brand profile and article destinations. Email is in development and not part of the API yet.

Building an assistant instead?

The same brands, posts and channels are on our MCP server, so Claude, ChatGPT and other clients use them without glue code.

07QUESTIONS

The API, answered.

01AUTHHow do I authenticate?

Create a key in Settings, then API, and send it as a bearer token to https://api.superagent.social/v1. A key belongs to one brand and cannot read another brand's posts, so keep it on your server.

01SUPERAGENT
02SPECIs there an OpenAPI spec?

Yes. The v1 surface ships as an OpenAPI 3.1 document, as JSON and YAML, so you can generate a typed client or load it into Postman or Insomnia. The docs show every call in curl, JavaScript, Node, Python and PHP.

02SUPERAGENT
03AICan I trigger AI generation through the API?

Yes. POST /v1/generate/text writes a caption and POST /v1/generate/image renders an image at a size you choose. POST /v1/campaigns queues a whole run. All three answer at once with a job, and you read the result back by id or by webhook.

03SUPERAGENT
04LIMITWhat are the rate limits?

60 requests a minute per key. Past that the API answers 429 and includes Retry-After. Every response carries X-RateLimit-Remaining. Agency plans get a higher ceiling on request.

04SUPERAGENT
05CONNECTCan my users connect their own accounts?

Yes. GET /v1/channels/connection-url returns a hosted link that starts connecting a network to the brand. The person signed in approves the network and picks the profiles.

05SUPERAGENT
06BRANDCan I read and update my brand?

GET /v1/brands/{brandId} returns the full profile: voice, keywords, hashtags, colours. PATCH changes any of them, with the same limits as the Brand page. Only brand owners and admins can update.

06SUPERAGENT
07EMAILDoes the API send email?

Not yet. Email is in development and will reuse the same scheduling model when it lands. Today the API covers social posts, AI drafts, campaigns, workflows and your brand profile.

07SUPERAGENT

Make your first call today.

Create a key, call /v1/brands, and post from your own code.