​
What You Need

Before you send requests, you need:

  1. An Ocoya API key
  2. A brand ID
  3. Social profile 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 social profiles

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

3

List social profiles

Call GET /social-profiles?brandId=BRAND_ID to find connected profile IDs.

4

Resolve optional context

Call GET /hashtag-libraries?brandId=BRAND_ID when an AI draft should use saved hashtag context.

5

Create a draft or scheduled post

Call POST /post?brandId=BRAND_ID with a caption, media URLs, target social profile 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

Manage posts

Use GET /post, 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"],
    "socialProfileIds": ["SOCIAL_PROFILE_ID"],
    "scheduledAt": "2026-07-01T09:00:00Z"
  }'

​
Connect A Social Profile

Use POST /social-profiles/connection-url when you need a browser URL for connecting a new social profile.

curl -X POST "https://www.app.ocoya.com/api/_public/v1/social-profiles/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 hashtagLibraryId and referenceDesignIds when you want the draft to use saved hashtag library or Studio template context.

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",
    "socialProfileIds": ["SOCIAL_PROFILE_ID"],
    "hashtagLibraryId": "HASHTAG_LIBRARY_ID",
    "generateImage": true,
    "referenceUrls": ["https://example.com/reference.png"],
    "referenceDesignIds": ["STUDIO_DESIGN_ID"]
  }'

​
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. Use hashtagLibraryId when the campaign should use a saved hashtag library.

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",
    "hashtagLibraryId": "HASHTAG_LIBRARY_ID",
    "socialProfileIds": ["SOCIAL_PROFILE_ID"],
    "generateMedia": true
  }'

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