> ## 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. # Start an Omni agent run > Queue the general Omni agent and return immediately with the run in `queued` state. Poll the URL in the `Location` header (`GET /api/v1/agents/general/runs/{runId}`), honoring `Retry-After`. Requires `agents:invoke`. The request body matches invoke. ## OpenAPI ````yaml /openapi.json post /api/v1/agents/general/runs 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: agents description: agents x-group: Agents - 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/agents/general/runs: post: tags: - agents summary: Start an Omni agent run description: >- Queue the general Omni agent and return immediately with the run in `queued` state. Poll the URL in the `Location` header (`GET /api/v1/agents/general/runs/{runId}`), honoring `Retry-After`. Requires `agents:invoke`. The request body matches invoke. operationId: post_v1_agents_general_runs requestBody: required: true content: application/json: schema: type: object properties: organizationId: type: string maxLength: 120 thread_id: anyOf: - type: string minLength: 1 maxLength: 200 - type: 'null' channel: type: string minLength: 1 maxLength: 64 messages: maxItems: 50 type: array items: type: object properties: role: type: string enum: - user - assistant - system content: anyOf: - type: string minLength: 1 maxLength: 100000 - minItems: 1 maxItems: 20 type: array items: oneOf: - type: object properties: type: type: string const: text text: type: string minLength: 1 maxLength: 100000 required: - type - text additionalProperties: false - type: object properties: type: type: string const: image url: type: string minLength: 1 maxLength: 2048 filename: type: string minLength: 1 maxLength: 200 required: - type - url additionalProperties: false id: type: string maxLength: 200 name: type: string maxLength: 200 required: - content additionalProperties: false config: type: object properties: enabled_tools: maxItems: 100 type: array items: type: string minLength: 1 maxLength: 128 model: anyOf: - type: string minLength: 1 maxLength: 200 - type: 'null' system_prompt: type: string maxLength: 20000 structured_output: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' additionalProperties: false decisions: maxItems: 20 type: array items: type: object properties: action: type: string enum: - approve - reject reason: type: string maxLength: 2000 required: - action additionalProperties: false additionalProperties: false example: messages: - role: user content: Summarize orders placed today. responses: '202': description: The agent run was queued. headers: Location: description: The run to poll. schema: type: string format: uri-reference Retry-After: description: >- Seconds to wait before polling again. Sent while the run is queued or running. schema: type: integer minimum: 1 content: application/json: schema: type: object properties: run_id: type: string thread_id: type: string status: type: string enum: - queued - running - completed - awaiting_approval - failed messages: type: array items: type: object properties: type: type: string enum: - human - ai - tool - system role: type: string enum: - user - assistant - tool - system content: type: string id: type: string name: type: string tool_calls: type: array items: type: object properties: id: type: string name: type: string args: {} required: - name - args tool_call_id: type: string required: - type - role - content structured_output: anyOf: - type: object propertyNames: type: string additionalProperties: {} - type: 'null' approvals: anyOf: - type: array items: type: object properties: interrupt_instance_id: type: string tool_name: anyOf: - type: string - type: 'null' tool_args: {} message: type: string required: - interrupt_instance_id - tool_name - tool_args - message - type: 'null' error: anyOf: - type: string - type: 'null' required: - run_id - thread_id - status - messages - structured_output - approvals - error '400': description: >- Invalid agent request, unknown tool or model, or a decision count that does not match the pending approvals '401': description: Unauthorized '402': description: Insufficient AI credits '403': description: Missing agents:invoke scope or Assistant access '409': description: >- The thread already has an active run, or decisions were sent for a thread with no run awaiting approval '500': description: The agent run failed. `data.run_id` identifies the stored run 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.