How to use

What You Need

Before you send requests, you need:

An Ocoya API key
A workspace ID
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

List workspaces

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

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.

List social profiles

Call GET /social-profiles?workspaceId=WORKSPACE_ID to find connected profile IDs.

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.

Create a draft or scheduled post

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

Create an AI draft

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

Create an AI campaign

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

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)

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.

Get Started

Fundamentals

API Reference

What You Need

Get An API Key

Base URL

Send Your First Request

Typical Publishing Flow

Create A Post

Create An AI Draft

Create An AI Campaign

MCP vs REST API

​What You Need

​Get An API Key

​Base URL

​Send Your First Request

​Typical Publishing Flow

​Create A Post

​Connect A Social Profile

​Create An AI Draft

​Create An AI Campaign

​MCP vs REST API

What You Need

Get An API Key

Base URL

Send Your First Request

Typical Publishing Flow

Create A Post

Connect A Social Profile

Create An AI Draft

Create An AI Campaign

MCP vs REST API