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"
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 GET /social-profiles/connection-url and open the returned authUrl 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

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"
  }'

​
Connect A Social Profile

Use GET /social-profiles/connection-url when you need a browser URL for connecting a new social profile.
cURL
curl -X GET "https://app.ocoya.com/api/_public/v1/social-profiles/connection-url?workspaceId=WORKSPACE_ID&provider=instagram" \
  -H "X-API-Key: YOUR_API_KEY"
Open the returned authUrl while signed in to Ocoya. Instagram returns a Facebook OAuth URL first because Instagram Business profiles are connected through Facebook Pages.

​
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",
    "length": "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"]
  }'

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