POST
https://www.app.ocoya.com/api/_public/v1/campaigns
Create an AI-generated campaign
curl --request POST \
  --url https://www.app.ocoya.com/api/_public/v1/campaigns \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "prompt": "Summer launch campaign for our ecommerce analytics dashboard.",
  "goal": "launch",
  "duration": 10,
  "startDate": "2026-11-02",
  "postsPerDay": 1,
  "count": 6,
  "postLength": "medium",
  "hashtagLibraryId": "cmayw7l5200067apsmz2tv7e8",
  "socialProfileIds": [
    "clh49poxf008x8kov4ncbjty9"
  ],
  "generateMedia": true,
  "imageCount": 3,
  "referenceUrls": [
    "https://example.com/reference.png"
  ],
  "referenceDesignIds": [
    "design_123"
  ]
}
'
{
  "campaignId": "cmayxcmpn00087aps2m7hjs9z",
  "status": "GENERATING",
  "queued": true,
  "generation": {}
}

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

Campaign prompt or brief.

Minimum string length: 3
Example:
"Summer launch campaign for our ecommerce analytics dashboard."
goalenum<string>

Campaign objective. Defaults to awareness.

Available options: awareness, leads, launch, offer, education, event
Example:"launch"
durationinteger

Campaign duration in days, from 1 to 90. Defaults to 7.

Required range: 1 <= x <= 90
Example:10
startDatestring

Day of the first post, YYYY-MM-DD. Must be tomorrow or later; anything else starts the campaign tomorrow.

Example:"2026-11-02"
postsPerDayenum<number>

How often to post: 0.5 is every other day, 1-4 is posts per day. Omit to spread count posts evenly over duration.

Available options: 0.5, 1, 2, 3, 4
Example:1
countinteger

Number of posts to generate, from 1 to 90. Defaults to 7.

Required range: 1 <= x <= 90
Example:6
postLengthenum<string>

Target caption length for each generated campaign post. Defaults to medium.

Available options: short, medium, long, extra_long
Example:"medium"
hashtagLibraryIdstring

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

Example:"cmayw7l5200067apsmz2tv7e8"
socialProfileIdsstring[]

Connected social profile IDs to attach when generated campaign posts are saved. Get IDs from GET /social-profiles.

Example:
[
  "clh49poxf008x8kov4ncbjty9"
]
generateMediaboolean

Whether to generate images for campaign posts.

Example:true
imageCountinteger

Number of images to generate for each campaign post, from 1 to 10. Values above 1 create carousel-style post creatives. Defaults to 1.

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

Optional image URLs to use as visual references when generateMedia is true. Maximum 3.

Maximum array length: 3
Example:
[
  "https://example.com/reference.png"
]
referenceDesignIdsstring[]

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

Maximum array length: 3
Example:
[
  "design_123"
]

Response

application/json

Campaign generation queued

campaignIdstring

ID of the campaign.

Example:"cmayxcmpn00087aps2m7hjs9z"
statusstring

GENERATING until every post is written.

Example:"GENERATING"
queuedboolean

Whether generation was queued.

Example:true
generationobject

Campaign generation progress metadata.

Example:{}