What You Need

Before you send requests, you need:

  1. An Ocoya API key
  2. A brand ID
  3. Channel IDs if you want to create or schedule posts

Get An API Key

Create or copy an API key from your Ocoya API settings.

Create API key

API keys are for server-side usage. Do not expose them in browser JavaScript, mobile apps, or public repositories.

Base URL

All REST API examples use:

https://www.app.ocoya.com/api/_public/v1

Send Your First Request

The fastest way to verify your API key is working is to call /me.

curl -X GET "https://www.app.ocoya.com/api/_public/v1/me" \
  -H "X-API-Key: YOUR_API_KEY"

If the key is valid, the API returns your user context.

{
  "id": "clx354swx0006ghoatnjknv98",
  "name": "Ocoya Support",
  "email": "support@ocoya.com"
}

Typical Publishing Flow

1

List brands

Call GET /brands and choose the brand you want to publish from.

2

Connect channels

If the brand has no connected channels yet, call POST /channels/connection-url and open the returned url in a browser.

3

List channels

Call GET /channels?brandId=BRAND_ID to find connected channel IDs.

4

Check the brand

Call GET /brands/{brandId} for the brand profile AI writing uses: description, tone of voice, guidelines, SEO keywords, hashtags and the brand score. Change it with PATCH /brands/{brandId}.

5

Create a draft or scheduled post

Call POST /post?brandId=BRAND_ID with a caption, media URLs, target channel IDs, and optional scheduledAt.

6

Create an AI draft

Call POST /post/ai?brandId=BRAND_ID with a prompt when you want Ocoya to generate the caption first.

7

Create an AI campaign

Call POST /campaigns?brandId=BRAND_ID to queue multi-post campaign generation and receive an immediate GENERATING response.

8

Follow the campaign

Call GET /campaigns/{campaignId}?brandId=BRAND_ID until its status is GENERATED, then use each post’s postGroupId with the post endpoints. GET /campaigns?brandId=BRAND_ID lists every campaign.

9

Manage posts

Use GET /post, GET /post/{postId}, PATCH /post/{postId}, and DELETE /post/{postId} to inspect, reschedule, or remove posts.

Create A Post

Use scheduledAt when you want a scheduled post. Omit it when you want a draft.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/post?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Launching our summer campaign today.",
    "mediaUrls": ["https://example.com/image.jpg"],
    "channelIds": ["CHANNEL_ID"],
    "scheduledAt": "2026-07-01T09:00:00Z"
  }'

Connect A Channel

Use POST /channels/connection-url when you need a browser URL for connecting a new channel.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/channels/connection-url?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"instagram"}'

Open the returned url while signed in to Ocoya.

Create An AI Draft

Use POST /post/ai when you want Ocoya to generate the caption from a prompt before creating the draft.

Use referenceDesignIds when you want the draft to use a Studio template as a visual reference. The caption follows the brand’s description, tone of voice and guidelines.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/post/ai?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Write a friendly launch post for our new analytics dashboard.",
    "tone": "friendly",
    "postLength": "medium",
    "channelIds": ["CHANNEL_ID"],
    "generateImage": true,
    "referenceUrls": ["https://example.com/reference.png"],
    "referenceDesignIds": ["STUDIO_DESIGN_ID"]
  }'

Use A Studio Design

To make every post’s image from one of the brand’s own Studio designs, pass studioDesignId to POST /post/ai or POST /campaigns. The AI writes the design’s text layers from the caption. Logos, photos and colours stay as designed; to swap one for this request, pass its field ID in studioDesignFields.

Find the brand’s designs with GET /studio-designs, and a design’s field IDs with GET /studio-designs/{designId}.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/post/ai?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Announce our weekend offer: 20% off every wash.",
    "studioDesignId": "STUDIO_DESIGN_ID",
    "studioDesignFields": {"IMAGE_FIELD_ID": "https://example.com/offer-photo.jpg"}
  }'

To render a design yourself, with no AI, use POST /studio-designs/{designId}/render with the values in fields. It returns the image url, which you can pass in mediaUrls to POST /post.

Create An AI Campaign

Use POST /campaigns when you want Ocoya to generate a multi-post campaign in the background.

The response returns immediately with GENERATING status. Captions use the brand’s own hashtags (see GET /brands/{brandId}).

curl -X POST "https://www.app.ocoya.com/api/_public/v1/campaigns?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summer launch campaign for our ecommerce analytics dashboard, aimed at marketing teams already using spreadsheets. Confident, practical tone.",
    "goal": "launch",
    "duration": 10,
    "count": 6,
    "postLength": "medium",
    "channelIds": ["CHANNEL_ID"],
    "generateMedia": true
  }'

Follow An AI Campaign

Use the campaignId from POST /campaigns to check progress. status is GENERATING until every post is written, then GENERATED; generation shows how far it got.

curl "https://www.app.ocoya.com/api/_public/v1/campaigns/CAMPAIGN_ID?brandId=BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY"

The response lists the campaign’s posts in order, each with a captionPreview, scheduledAt, and, once the campaign has saved it, the postGroupId and post status. Use GET /campaigns?brandId=BRAND_ID to list campaigns, newest first, optionally filtered by status.

Read And Update The Brand

GET /brands/{brandId} returns the brand profile: description, website, logos, colors, fonts, tone of voice, writing guidelines, SEO keywords with monthly searches, hashtags, and the brand score out of 100 with its suggested next step.

PATCH /brands/{brandId} changes any of description, url, tone, guidelines, keywords, hashtags and colors, checked the same way as on the Brand page. Only brand owners and admins can change a brand.

curl -X PATCH "https://www.app.ocoya.com/api/_public/v1/brands/BRAND_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tone": ["Friendly", "Expert"],
    "keywords": ["social media scheduler", "ai captions"]
  }'

MCP vs REST API

Use the REST API for backend systems that already know exactly what they need to do.

Use MCP when you want AI clients such as Claude, Codex, or ChatGPT to discover and call Ocoya tools after the user approves OAuth access.