Sign in

v1

latestOpenAPI 3.1.02026-08-0616024.0 KB

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.

post/campaigns

Query parameters

workspaceIdstring required
Example:cmayvq3hk00017apshay5qezu

Ocoya workspace ID. Get one from GET /workspaces.

Request body

promptstring required

Campaign prompt or brief.

goal'awareness' | 'leads' | 'launch' | 'offer' | 'education' | 'event'

Campaign objective.

audience'business_owners' | 'founders_executives' | 'marketing_teams' | 'buyers_customers' | 'local_community' | 'investors' | 'first_time_buyers' | 'existing_customers'

Primary campaign audience.

durationinteger

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

countinteger

Number of posts to generate, from 3 to 30. Defaults to 5.

postLength'short' | 'medium' | 'long' | 'extra_long'

Target caption length for each generated campaign post.

tone'professional' | 'friendly' | 'educational' | 'bold' | 'founder_led'

Caption tone for campaign posts.

brandIdstring

Brand kit ID used for brand context. When campaign media is generated, brand kit logos and icons are treated as protected reference assets. Get IDs from GET /brand-kits.

hashtagLibraryIdstring

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

socialProfileIdsstring[]

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

generateMediaboolean

Whether to generate images for campaign posts.

imageCountinteger

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

referenceUrlsstring[]

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

referenceDesignIdsstring[]

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

Example request

{
  "prompt": "Summer launch campaign for our ecommerce analytics dashboard.",
  "goal": "launch",
  "audience": "marketing_teams",
  "duration": 10,
  "count": 6,
  "postLength": "medium",
  "tone": "professional",
  "brandId": "cmayw38dz00047apsue9nw4tf",
  "hashtagLibraryId": "cmayw7l5200067apsmz2tv7e8",
  "socialProfileIds": [
    "clh49poxf008x8kov4ncbjty9"
  ],
  "generateMedia": true,
  "imageCount": 3,
  "referenceUrls": [
    "https://example.com/reference.png"
  ],
  "referenceDesignIds": [
    "design_123"
  ]
}

Response

Campaign generation queued

campaignIdstring
statusstring
queuedboolean
generationobject

Campaign generation progress metadata.

Example response

{
  "campaignId": "cmayxcmpn00087aps2m7hjs9z",
  "status": "GENERATING",
  "queued": true
}