Your API key. Create one in Ocoya. Authorization: Bearer <key> works too.
Create an AI-generated campaign
Queues generation for a multi-post AI campaign and returns immediately with GENERATING status. Campaign posts are generated asynchronously in the background.
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
Body
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.
Day of the first post, YYYY-MM-DD. Must be tomorrow or later; anything else starts the campaign tomorrow.
How often to post: 0.5 is every other day, 1-4 is posts per day. Omit to spread count posts evenly over duration.
Channel IDs to attach when generated campaign posts are saved. Get IDs from GET /channels.
Number of images to generate for each campaign post, from 1 to 10. Values above 1 create carousel-style post creatives. Defaults to 1.
Optional image URLs to use as visual references when generateMedia is true. Maximum 3.
Optional Studio design IDs to use as visual references when generateMedia is true. Get IDs from GET /studio-templates. Maximum 3.
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.
seo only: the shape of each post's AI thumbnail when generateMedia is true. Defaults to 16:9.
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.
email only: the exact ISO 8601 send time of each email, instead of count, startDate and postsPerDay. Up to 10.
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.
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.
Was this page helpful?