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

# List Campaigns

> List campaigns for the authenticated organization. `stage=all` is the workspace working set: draft and running. Requires `promotions:read`.



## OpenAPI

````yaml /openapi.json get /api/v1/campaigns
openapi: 3.1.0
info:
  title: OmniCommerce API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://omnicommerce.sg/terms
  description: >-
    OmniCommerce API surface for agents and developer integrations. Includes
    public endpoints (merchant discovery, product search, compare, catalog, ACO
    retrieval) and authenticated endpoints (product management via API key
    Bearer tokens).
servers:
  - url: https://omnicommerce.sg
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags:
  - name: agentic-checkout
    description: Merchant-fulfilled agentic checkout
    x-group: Agentic Checkout
  - name: aops
    description: Agent operating procedures
    x-group: AOPs
  - name: campaigns
    description: Campaign briefs, offer windows, and marketplace runs
    x-group: Campaigns
  - name: commerce
    description: Root commerce discovery
    x-group: Commerce
  - name: developer-platform
    description: Authenticated developer platform APIs
    x-group: Developer Platform
  - name: looks
    description: AI-styled product looks
    x-group: Looks
  - name: oauth
    description: OAuth token endpoints
    x-group: OAuth
  - name: orders
    description: Workspace and agentic orders
    x-group: Orders
  - name: organizations
    description: Organization management
    x-group: Organizations
  - name: price-books
    description: Marketplace list-price markup rules
    x-group: Price Books
  - name: products
    description: Product CRUD, bulk import, enrichment, publish, and delist
    x-group: Products
  - name: promotions
    description: Central promotions and marketplace sync
    x-group: Promotions
  - name: public-agent
    description: Public agent discovery and catalog APIs
    x-group: Public Agent
  - name: returns
    description: returns
    x-group: Returns
  - name: settlements
    description: settlements
    x-group: Settlements
  - name: ucp
    description: Universal Commerce Protocol
    x-group: UCP
paths:
  /api/v1/campaigns:
    get:
      tags:
        - campaigns
      summary: List Campaigns
      description: >-
        List campaigns for the authenticated organization. `stage=all` is the
        workspace working set: draft and running. Requires `promotions:read`.
      operationId: get_v1_campaigns
      parameters:
        - name: organizationId
          in: query
          required: false
          description: >-
            Optional organization scope for session-authenticated calls. OAuth
            client credentials resolve the organization from the token.
          schema:
            type: string
            maxLength: 120
        - name: q
          in: query
          required: false
          description: Search campaign name.
          schema:
            default: ''
            type: string
            maxLength: 160
        - name: stage
          in: query
          required: false
          description: >-
            `all` lists draft and running campaigns. Any other value lists that
            stage only.
          schema:
            default: all
            type: string
            enum:
              - all
              - draft
              - approved
              - running
              - ending
              - completed
              - archived
        - name: offset
          in: query
          required: false
          schema:
            default: 0
            type: integer
            minimum: 0
            maximum: 100000
        - name: limit
          in: query
          required: false
          schema:
            default: 20
            type: integer
            minimum: 1
            maximum: 50
      responses:
        '200':
          description: Campaign page and stage summary.
          content:
            application/json:
              schema:
                type: object
                properties:
                  campaigns:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        organizationId:
                          type: string
                        revision:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        stage:
                          type: string
                          enum:
                            - draft
                            - approved
                            - running
                            - ending
                            - completed
                            - archived
                        approval:
                          anyOf:
                            - type: object
                              properties:
                                revision:
                                  type: integer
                                  minimum: -9007199254740991
                                  maximum: 9007199254740991
                                userId:
                                  type: string
                                approvedAt:
                                  type: string
                              required:
                                - revision
                                - userId
                                - approvedAt
                            - type: 'null'
                        runId:
                          anyOf:
                            - type: string
                            - type: 'null'
                        startedAt:
                          anyOf:
                            - type: string
                            - type: 'null'
                        endedAt:
                          anyOf:
                            - type: string
                            - type: 'null'
                        createdAt:
                          type: string
                        updatedAt:
                          type: string
                        name:
                          type: string
                        brand:
                          type: string
                        storeCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        windowCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        offerCount:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        cleanupFailed:
                          type: boolean
                      required:
                        - id
                        - organizationId
                        - revision
                        - stage
                        - approval
                        - runId
                        - startedAt
                        - endedAt
                        - createdAt
                        - updatedAt
                        - name
                        - brand
                        - storeCount
                        - windowCount
                        - offerCount
                  total:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  hasMore:
                    type: boolean
                  nextOffset:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  summary:
                    type: object
                    properties:
                      totalCount:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                        description: Draft and running campaigns matching `q`.
                      stageCounts:
                        type: object
                        propertyNames:
                          type: string
                          enum:
                            - draft
                            - approved
                            - running
                            - ending
                            - completed
                            - archived
                        additionalProperties:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                    required:
                      - totalCount
                      - stageCounts
                  pagination:
                    type: object
                    properties:
                      offset:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      limit:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      total:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      hasMore:
                        type: boolean
                      nextOffset:
                        anyOf:
                          - type: integer
                            minimum: 0
                            maximum: 9007199254740991
                          - type: 'null'
                      maxLimit:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                      defaultLimit:
                        type: integer
                        minimum: 0
                        maximum: 9007199254740991
                    required:
                      - offset
                      - limit
                      - total
                      - hasMore
                      - nextOffset
                      - maxLimit
                      - defaultLimit
                required:
                  - campaigns
                  - total
                  - hasMore
                  - nextOffset
                  - summary
                  - pagination
        '400':
          description: Invalid campaign payload or plan state.
        '401':
          description: Unauthorized
        '403':
          description: >-
            Forbidden: missing `promotions:read` scope, or a session member
            without organization-wide access
        '429':
          description: Rate limit exceeded
        '500':
          description: Internal Server Error
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: >-
        Bearer API key for server-to-server access. Session auth is also
        supported in first-party UI flows.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.