What You Need
Before you send requests, you need:
- An Ocoya API key
- A brand ID
- 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.
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/v1Send 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
List brands
Call GET /brands and choose the brand you want to publish from.
Connect channels
If the brand has no connected channels yet, call POST /channels/connection-url and open the returned url in a browser.
List channels
Call GET /channels?brandId=BRAND_ID to find connected channel IDs.
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}.
Create a draft or scheduled post
Call POST /post?brandId=BRAND_ID with a caption, media URLs, target channel IDs, and optional scheduledAt.
Create an AI draft
Call POST /post/ai?brandId=BRAND_ID with a prompt when you want Ocoya to generate the caption first.
Create an AI campaign
Call POST /campaigns?brandId=BRAND_ID to queue multi-post campaign generation and receive an immediate GENERATING response.
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.
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.