POST
https://www.app.ocoya.com/api/_public/v1/post/ai
Create an AI-generated draft post
curl --request POST \
  --url https://www.app.ocoya.com/api/_public/v1/post/ai \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": "Write a launch post for our new analytics dashboard.",
  "tone": "professional",
  "postLength": "medium",
  "socialProfileIds": [
    "clh49poxf008x8kov4ncbjty9"
  ],
  "hashtagLibraryId": "cmayw7l5200067apsmz2tv7e8",
  "generateImage": true,
  "imageCount": 3,
  "referenceUrls": [
    "https://example.com/reference.png"
  ],
  "referenceDesignIds": [
    "design_123"
  ]
}
'
{
  "postGroupId": "cmajvvb9q0003ja5vh0538j6r",
  "status": "GENERATING",
  "scheduledAt": null
}

Authorizations

X-API-Keystringheaderrequired

Your API key. Create one in Ocoya. Authorization: Bearer <key> works too.

Query Parameters

brandIdstringrequired

Ocoya brand ID. Get one from GET /brands.

Example:"cmayvq3hk00017apshay5qezu"

Body

application/json
promptstringrequired

Prompt describing the post Ocoya should generate. Minimum 10 characters.

Minimum string length: 10
Example:"Write a launch post for our new analytics dashboard."
toneenum<string>

Caption tone for the AI draft. Defaults to professional.

Available options: professional, friendly, educational, bold, founder_led
Example:"professional"
postLengthenum<string>

Target caption length for the AI draft. Defaults to medium.

Available options: short, medium, long, extra_long
Example:"medium"
socialProfileIdsstring[]

Connected social profile IDs that should receive the post. Get IDs from GET /social-profiles.

Example:
[
  "clh49poxf008x8kov4ncbjty9"
]
hashtagLibraryIdstring

Hashtag library ID used for hashtag context. Get IDs from GET /hashtag-libraries.

Example:"cmayw7l5200067apsmz2tv7e8"
generateImageboolean

Whether to generate square image media for the AI draft.

Example:true
imageCountinteger

Number of generated images when generateImage is true. Use 1 for a single image or 2-10 for a carousel.

Required range: 1 <= x <= 10
Example:3
referenceUrlsstring[]

Optional image URLs to use as visual references when generateImage is true. Ocoya uses these images for style, composition, layout, and subject guidance; they are not attached directly to the post.

Example:
[
  "https://example.com/reference.png"
]
referenceDesignIdsstring[]

Optional Studio design IDs to use as visual references when generateImage is true. Get IDs from GET /studio-templates.

Example:
[
  "design_123"
]

Response

application/json

Queued. Returns immediately with status GENERATING; fetch the post later to see the completed draft.

postGroupIdstring

ID of the post. Fetch it later with GET /post to see the finished draft.

Example:"cmajvvb9q0003ja5vh0538j6r"
statusstring

GENERATING until the caption and media are ready.

Example:"GENERATING"
scheduledAtstring | null

When the post is scheduled, or null for a draft.