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 '
{
  "type": "social",
  "prompt": "Summer launch campaign for our ecommerce analytics dashboard.",
  "goal": "launch",
  "duration": 10,
  "startDate": "2026-11-02",
  "postsPerDay": 1,
  "count": 6,
  "postLength": "medium",
  "channelIds": [
    "clh49poxf008x8kov4ncbjty9"
  ],
  "generateMedia": true,
  "imageCount": 3,
  "referenceUrls": [
    "https://example.com/reference.png"
  ],
  "referenceDesignIds": [
    "design_123"
  ],
  "studioDesignId": "design_123",
  "thumbnailAspectRatio": "16:9",
  "studioDesignFields": {
    "pixy-cmte3datf00f435708hleujti": "https://example.com/logo.png"
  },
  "sendTimes": [
    "2026-12-01T09:00:00Z",
    "2026-12-03T09:00:00Z"
  ],
  "audience": {
    "groupIds": [
      "<string>"
    ],
    "excludeGroupIds": [
      "<string>"
    ]
  },
  "templateId": "auto",
  "productIds": [
    "<string>"
  ]
}
'
{
  "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."
typeenum<string>

Kind of campaign. social (default) writes social posts; seo writes SEO posts for blog channels, one keyword-researched post per entry, spread over duration days (1-20 posts, 3 by default); email writes count emails (1-10, 3 by default, a brief of 10+ characters) to the brand's contacts, planned from startDate at postsPerDay (0.5, 1 or 2, at 10:00 and 16:00 in the brand's timezone): read it with GET /campaigns/{campaignId}, which lists its emails, and send it with POST /campaigns/{campaignId}/schedule.

Available options: social, seo, email
Example:"social"
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"
channelIdsstring[]

Channel IDs to attach when generated campaign posts are saved. Get IDs from GET /channels.

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"
]
studioDesignIdstring

Optional ID of the brand's own Studio design, from GET /studio-designs. Every post's image is then that design, with its text layers written by the AI from each caption. Every other layer stays as designed unless set in studioDesignFields. imageCount and references are ignored.

Example:"design_123"
thumbnailAspectRatioenum<string>

seo only: the shape of each post's AI thumbnail when generateMedia is true. Defaults to 16:9.

Available options: 16:9, 1:1, 4:5
Example:"16:9"
studioDesignFieldsobject

Optional values for the Studio design's layers, keyed by field ID from GET /studio-designs/{designId}: an image URL for an image field (a logo, a product photo), a CSS colour for a colour field, or text for a text field, which is then used as given instead of being written by the AI. Only used with studioDesignId.

Example:
{
  "pixy-cmte3datf00f435708hleujti": "https://example.com/logo.png"
}
sendTimesstring[]

email only: the exact ISO 8601 send time of each email, instead of count, startDate and postsPerDay. Up to 10.

Maximum array length: 10
Example:
[
  "2026-12-01T09:00:00Z",
  "2026-12-03T09:00:00Z"
]
audienceobject

email only: who the emails go to. Every subscribed contact when groupIds is empty; otherwise the contacts in any of groupIds, minus anyone in excludeGroupIds. Group IDs from GET /contacts/groups.

Show child attributesHide child attributes
audience.groupIdsstring[]
audience.excludeGroupIdsstring[]
templateIdstring

email only: the template every email is written in, from GET /email/templates, or auto to pick the best fit. Left out: the AI's own layout.

Example:"auto"
productIdsstring[]

email only: the brand's products the campaign is about.

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:{}