> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocoya.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.



## OpenAPI

````yaml /openapi.yaml post /campaigns
openapi: 3.1.0
info:
  version: 1.1.0
  title: Ocoya API
  description: REST API reference for Ocoya.
servers:
  - url: https://app.ocoya.com/api/_public/v1
security:
  - ApiKeyAuth: []
paths:
  /campaigns:
    post:
      summary: Create an AI-generated campaign
      description: >-
        Queues generation for a multi-post AI campaign and returns immediately
        with `GENERATING` status. Campaign posts are generated asynchronously in
        the background.
      parameters:
        - in: query
          name: workspaceId
          required: true
          description: Ocoya workspace ID. Get one from `GET /workspaces`.
          schema:
            type: string
            example: cmayvq3hk00017apshay5qezu
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - prompt
              properties:
                prompt:
                  type: string
                  description: Campaign prompt or brief.
                  minLength: 3
                  example: >-
                    Summer launch campaign for our ecommerce analytics
                    dashboard.
                goal:
                  type: string
                  description: Campaign objective.
                  enum:
                    - awareness
                    - leads
                    - launch
                    - offer
                    - education
                    - event
                  example: launch
                audience:
                  type: string
                  description: Primary campaign audience.
                  enum:
                    - business_owners
                    - founders_executives
                    - marketing_teams
                    - buyers_customers
                    - local_community
                    - investors
                    - first_time_buyers
                    - existing_customers
                  example: marketing_teams
                duration:
                  type: integer
                  description: Campaign duration in days, from 1 to 30. Defaults to 7.
                  minimum: 1
                  maximum: 30
                  example: 10
                count:
                  type: integer
                  description: Number of posts to generate, from 3 to 30. Defaults to 5.
                  minimum: 3
                  maximum: 30
                  example: 6
                postLength:
                  type: string
                  description: Target caption length for each generated campaign post.
                  enum:
                    - short
                    - medium
                    - long
                    - extra_long
                  example: medium
                tone:
                  type: string
                  description: Caption tone for campaign posts.
                  enum:
                    - professional
                    - friendly
                    - educational
                    - bold
                    - founder_led
                  example: professional
                brandId:
                  type: string
                  description: >-
                    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`.
                  example: cmayw38dz00047apsue9nw4tf
                hashtagLibraryId:
                  type: string
                  description: >-
                    Hashtag library ID used for hashtag context. Get IDs from
                    `GET /hashtag-libraries`.
                  example: cmayw7l5200067apsmz2tv7e8
                socialProfileIds:
                  type: array
                  description: >-
                    Connected social profile IDs to attach when generated
                    campaign posts are saved. Get IDs from `GET
                    /social-profiles`.
                  items:
                    type: string
                  example:
                    - clh49poxf008x8kov4ncbjty9
                generateMedia:
                  type: boolean
                  description: Whether to generate one image for each campaign post.
                  example: true
                referenceUrls:
                  type: array
                  description: >-
                    Optional image URLs to use as visual references when
                    `generateMedia` is `true`. Maximum 3.
                  items:
                    type: string
                  example:
                    - https://example.com/reference.png
                referenceDesignIds:
                  type: array
                  description: >-
                    Optional Studio design IDs to use as visual references when
                    `generateMedia` is `true`. Get IDs from `GET
                    /studio-templates`. Maximum 3.
                  items:
                    type: string
                  example:
                    - design_123
      responses:
        '202':
          description: Campaign generation queued
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaignId:
                    type: string
                    example: cmayxcmpn00087aps2m7hjs9z
                  status:
                    type: string
                    example: GENERATING
                  queued:
                    type: boolean
                    example: true
                  generation:
                    type: object
                    description: Campaign generation progress metadata.
        '400':
          description: Invalid request
        '500':
          description: Unknown error
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key

````