Ocoya
Ocoya API

Your marketing copilot, one request away.

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

One request, many places

You send it once. It reaches every channel.

Your code makes one call with a caption, media and channel IDs. Ocoya schedules it, publishes it to every connected channel and keeps its status up to date.

Your app

POST /post
{ "caption", "mediaUrls",
  "channelIds", "scheduledAt" }

Ocoya

Schedules, publishes, tracks

Social networks

Blogs and sites

Webflow and Framer collections and a Wix blog receive articles.

Endpoint explorer

Every endpoint, on one wall.

Pick one to see what it does and what it takes. This is the whole v1 surface, straight from the spec.

// Account and brands

// Channels

// Library

// Posts

// AI and campaigns

// Workflows

POST/post

Creates a post. Add scheduledAt to schedule it, leave it out to save a draft.

Takes

brandIdcaptionmediaUrlschannelIdsscheduledAt

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 Ocoya.

Good to know

  • A key reaches every brand your account owns. It cannot be limited to one brand.
  • Ocoya shows the key once. Copy it as soon as you create it.
  • Deleting a key stops it at once. To swap one, create the new key first, move over, then delete the old one.
01

Create a key

Settings, then API. Name it after where it runs, like “staging server”, so you know what breaks if you delete it.

Settings → API → Create token
02

Send it as X-API-Key

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

X-API-Key: ••••••••••••a91f
03

Call /me

You get your account back, then /brands gives you the brandId the other calls need.

$ curl "$OCOYA/me" -H "X-API-Key: $KEY"

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

schedule.sh
curl -X POST "https://www.app.ocoya.com/api/_public/v1/post?brandId=$BRAND_ID" \
  -H "X-API-Key: $OCOYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Doors open at 9 on Saturday",
    "channelIds": ["ch_instagram", "ch_linkedin"],
    "scheduledAt": "2026-11-07T08:00:00Z"
  }'

This one schedules a post to two channels for a set time.

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 you can generate a typed client or load it into Postman or Insomnia.

  • Generate a client from the spec
  • Try any call from the docs in your browser
  • Shapes stay in step with the API
200OK201Post created202Campaign queued400Invalid request429Over 60 a minute, slow down500Unknown error
Async by default

AI work never holds up your request.

Ask for an AI draft or a campaign and the answer comes straight back, with status GENERATING. The posts fill in behind the scenes. Read them back with GET /post whenever you like.

ocoya · POST /campaigns · 202

202 in a blink

POST /campaigns answers with a campaignId and queued: true. GET /campaigns/{campaignId} shows its progress.

Filter by status

Ask GET /post for any status, from GENERATING to POSTED.

Approval aware

Posts waiting on a teammate or a client show it in their status.

Post statuses you can filter on

  • GENERATINGAI is still writing or making images.
  • DRAFTSaved, not scheduled.
  • PENDING_INTERNAL_APPROVALWaiting on a teammate.
  • PENDING_CLIENT_APPROVALWaiting on the client.
  • SCHEDULEDQueued for its time.
  • POSTEDLive on the network.
  • ERRORPublishing failed, with the reason on the post.
Your endpoint as a channel

Posts can land on your own URL too.

Add a Custom channel in the app and Ocoya POSTs each post to your URL 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
{
  "event": "post.published",
  "post": {
    "id": "clx…",
    "title": "…",
    "caption": "…",
    "image": "https://…",
    "options": { "slug": "…" }
  }
}
POSTpost.deleted
{
  "event": "post.deleted",
  "id": "9f2c1a",
  "post": { … }
}

Your endpoint replies

HTTP/1.1 200 OK
{
  "id": "9f2c1a",
  "url": "https://yourblog.com/post"
}
  • 1A 2xx statusAnything else is recorded as a failed publish.
  • 2An idYour own id for what you created. Deletes use it.
  • 3A urlWhere it went live. It becomes the post’s View post link.

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

Custom channels are added in the app, under Channels, Connect channel, Custom.

Build it with Ocoya

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 POST /post sends them to the channels your customer picked.

1.GET /channels2.POST /post
recipe_02

AI drafts from product events

A new feature ships, your backend asks POST /post/ai for a draft in a friendly tone. Someone checks it before it goes out.

1.POST /post/ai2.GET /post
recipe_03

A campaign in one click

Put a “launch campaign” button in your admin. It queues a week of posts with images, and you read the campaign back with its posts once they are written.

1.POST /campaigns2.GET /campaigns/{campaignId}
recipe_04

Brand voice from your own tools

Keep the tone of voice, keywords and hashtags in your CMS or CRM, and sync them to the brand so every AI post uses them.

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

Articles to your blog

Connect a WordPress, Webflow, Framer or Wix site as a channel, and your posts have a blog to land on as well as socials.

1.POST /channels/connection-url2.POST /post
recipe_06

Automations on a switch

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

1.GET /workflow2.POST /workflow/{workflowId}
Under the hood

The same engine as the app.

The API runs on what powers Ocoya itself. Posts you create in code show up in the calendar next to everything else and publish the same way.

✓ Same calendar

✓ Same AI

✓ Same channels

✓ Same credits

AI drafts and campaigns use the same credits as the app.

What the API covers today

Social posts, AI campaigns, your brand profile and article destinations. Email is coming soon to Ocoya and is not part of the API yet.

Building an AI agent instead?

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

Explore MCP

Ocoya›API›Questions

The API, answered.

v1OpenAPI 3.17
  1. Create a key in Settings, then API, and send it in the X-API-Key header to https://www.app.ocoya.com/api/_public/v1. A key can reach every brand your account owns, so keep it on your server.

  2. Yes. The whole v1 surface is an OpenAPI 3.1 document, so you can generate a typed client or load it into your API tooling. The docs show each call in curl, JavaScript, Node, Python and PHP.

  3. Yes. POST /post/ai writes a single draft, with images if you ask. POST /campaigns queues a whole campaign of up to 30 posts. Both answer straight away with status GENERATING, and the posts fill in in the background. GET /campaigns lists your campaigns, and GET /campaigns/{campaignId} shows one with its status and posts.

  4. Each key gets 60 requests a minute. Past that, the API answers 429 Too Many Requests. Wait for the window to reset, then retry.

  5. POST /channels/connection-url gives you a link that starts connecting a network to a brand. It is opened while signed in to Ocoya, where the person approves the network and picks profiles.

  6. Yes. GET /brands/{brandId} returns the full profile, with tone of voice, keywords, hashtags and the brand score. PATCH /brands/{brandId} changes the description, website, tone, guidelines, keywords, hashtags or colors, with the same limits as the Brand page. Only brand owners and admins can update a brand.

  7. No. Email is coming soon to Ocoya, and the API covers social posts, AI campaigns, your brand profile and article destinations today.

Make your first call today.

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