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

# Execute an AOP

> Start an AOP run and return immediately with a `thread_id`. Poll `GET /api/v1/threads/{thread_id}/status`. Requires `aops:write`.



## OpenAPI

````yaml /openapi.json post /api/v1/aop/{aopId}/execute
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: 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, and publish
    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/aop/{aopId}/execute:
    post:
      tags:
        - aops
      summary: Execute an AOP
      description: >-
        Start an AOP run and return immediately with a `thread_id`. Poll `GET
        /api/v1/threads/{thread_id}/status`. Requires `aops:write`.
      operationId: post_v1_aop_by_aopid_execute
      parameters:
        - name: aopId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                dry_run:
                  type: boolean
                  default: false
                  description: >-
                    Execute as a Test run: the agent uses its real prompt,
                    config, and read-only tools, but side-effectful tool calls
                    are captured instead of executed.
                user_inputs:
                  type:
                    - object
                    - 'null'
                  additionalProperties:
                    type:
                      - string
                      - number
                      - boolean
                  description: >-
                    Optional user inputs appended to the AOP prompt as key-value
                    pairs.
                organizationId:
                  type: string
                  maxLength: 120
                  description: Required for session auth. Optional for API keys.
            example:
              user_inputs:
                company: Acme Corp
                quarter: Q1 2024
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                required:
                  - status
                  - thread_id
                  - sync_server
                  - trigger_type
                  - aop_id
                  - aop_title
                  - base_prompt
                  - final_prompt
                  - aop_config
                properties:
                  status:
                    type: string
                    example: started
                  thread_id:
                    type: string
                  sync_server:
                    type: string
                    description: OmniCommerce origin. Clients can ignore this field.
                  trigger_type:
                    type: string
                    const: api
                  message:
                    type: string
                  aop_id:
                    type: string
                  aop_title:
                    type: string
                  base_prompt:
                    type: string
                  final_prompt:
                    type: string
                  aop_config:
                    type: object
                    additionalProperties: true
                  conversation:
                    type: object
                    additionalProperties: true
              example:
                status: started
                thread_id: agent-aop-run_1
                sync_server: https://omnicommerce.sg
                trigger_type: api
                message: >-
                  Task execution started successfully. Use the thread_id to
                  track progress.
                aop_id: aop_1
                aop_title: Market Research Report Generator
                base_prompt: Generate a comprehensive market research report
                final_prompt: |
                  Generate a comprehensive market research report

                  --- User Inputs ---
                  company: Acme Corp
                aop_config:
                  agentId: research
        '400':
          description: Invalid AOP configuration or request
        '401':
          description: Unauthorized
        '402':
          description: Insufficient AI credits
        '403':
          description: Forbidden. Missing OAuth scope.
        '404':
          description: AOP or thread not found
        '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.

````