Skip to main content

​
What You Need

Before you send requests, you need:
  1. An Ocoya API key
  2. A workspace 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://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://app.ocoya.com/api/_public/v1/me" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch('https://app.ocoya.com/api/_public/v1/me', {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'X-API-Key': process.env.OCOYA_API_KEY,
  },
})

const me = await response.json()
console.log(me)

import os
import requests

response = requests.get(
    "https://app.ocoya.com/api/_public/v1/me",
    headers={"X-API-Key": os.environ["OCOYA_API_KEY"]},
)

print(response.json())
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 workspaces

Call GET /workspaces and choose the workspace you want to publish from.
2

Connect social profiles

If the workspace 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?workspaceId=WORKSPACE_ID to find connected profile IDs.
4

Resolve optional context

Call GET /brand-kits?workspaceId=WORKSPACE_ID and GET /hashtag-libraries?workspaceId=WORKSPACE_ID when an AI draft should use saved brand or hashtag context.
5

Create a draft or scheduled post

Call POST /post?workspaceId=WORKSPACE_ID with a caption, media URLs, target social profile IDs, and optional scheduledAt.
6

Create an AI draft

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

Create an AI campaign

Call POST /campaigns?workspaceId=WORKSPACE_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://app.ocoya.com/api/_public/v1/post?workspaceId=WORKSPACE_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"
  }'

const response = await fetch('https://app.ocoya.com/api/_public/v1/post?workspaceId=WORKSPACE_ID', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.OCOYA_API_KEY,
  },
  body: JSON.stringify({
    caption: 'Launching our summer campaign today.',
    mediaUrls: ['https://example.com/image.jpg'],
    socialProfileIds: ['SOCIAL_PROFILE_ID'],
    scheduledAt: '2026-07-01T09:00:00Z',
  }),
})

const post = await response.json()
console.log(post)

​
Connect A Social Profile

Use POST /social-profiles/connection-url when you need a browser URL for connecting a new social profile.
cURL
curl -X POST "https://app.ocoya.com/api/_public/v1/social-profiles/connection-url?workspaceId=WORKSPACE_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 brandId, hashtagLibraryId, and referenceDesignIds when you want the draft to use saved brand kit, hashtag library, or Studio template context.
cURL
curl -X POST "https://app.ocoya.com/api/_public/v1/post/ai?workspaceId=WORKSPACE_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"],
    "brandId": "BRAND_KIT_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
curl -X POST "https://app.ocoya.com/api/_public/v1/campaigns?workspaceId=WORKSPACE_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Summer launch campaign for our ecommerce analytics dashboard",
    "goal": "launch",
    "audience": "marketing_teams",
    "duration": 10,
    "count": 6,
    "postLength": "medium",
    "tone": "professional",
    "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.