OCocoya
Campaigns

Create an AI-generated campaign

Changed on

Queues generation for a multi-post AI campaign and returns immediately with GENERATING status. Campaign posts are generated asynchronously in the background.

post/campaigns

Request

  • Base URL
    https://www.app.ocoya.com/api/_public/v1
  • Auth
    API key in header X-API-Key

Query parameters

brandIdstring required
Example:cmayvq3hk00017apshay5qezu

Ocoya brand ID. Get one from GET /brands.

Request body

promptstring required

Campaign prompt or brief.

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

Campaign objective. Defaults to awareness.

durationinteger

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

startDatestring

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

countinteger

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

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

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

channelIdsstring[]

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

generateMediaboolean

Whether to generate images for campaign posts.

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.

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.

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.

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 request

{
  "prompt": "Summer launch campaign for our ecommerce analytics dashboard.",
  "goal": "launch",
  "duration": 10,
  "startDate": "2026-11-02",
  "count": 6,
  "postLength": "medium",
  "channelIds": [
    "clh49poxf008x8kov4ncbjty9"
  ],
  "generateMedia": true,
  "imageCount": 3,
  "referenceUrls": [
    "https://example.com/reference.png"
  ],
  "referenceDesignIds": [
    "design_123"
  ],
  "studioDesignId": "design_123",
  "studioDesignFields": {
    "pixy-cmte3datf00f435708hleujti": "https://example.com/logo.png"
  }
}

Response

Campaign generation queued

campaignIdstring required

ID of the campaign.

statusstring required

GENERATING until every post is written.

queuedboolean required

Whether generation was queued.

generationobject required

Campaign generation progress metadata.

Example response

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

Changes

  • ef9bd3530850Revision changes
    • warning

      removed the request property

    • warning

      removed the request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

  • ad0d7f3cdd9bRevision changes
    • info

      api operation id createCampaign was added

    • info

      api tag Campaigns added

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      the request property's max was increased from 30.00 to 90.00

    • info

      the request property's max was increased from 30.00 to 90.00

    • info

      added the media type application/json for the response with the status

    • info

      added the media type application/json for the response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      the response property became required for the status

    • info

      added 'propertyNames' constraint to the response property for the status