> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnicommerce.ai/llms.txt > Use this file to discover all available pages before exploring further. # Send a message to an agent > Message the exact built-in or custom agent in the URL, using its saved model, instructions, tools, permissions and Programmatic starting mode. ### Authentication Requires an API key with `agents:invoke`, or a sign-in session. Organization-owned keys use their recorded creator's current membership and agent access; keys without a valid owner are refused. API keys identify their organization; session requests include `organizationId`. ### Conversation and execution - The same caller, agent and `clientThreadKey` continue one conversation. Different callers, agents and organizations are isolated. - No model, prompt or tool overrides are accepted. - `wait=false` queues durable work and returns 202; `wait=true` returns the final reply or pending approvals. - Send `decisions` with the same `clientThreadKey` to approve or reject a paused run. ## OpenAPI ````yaml /openapi.json post /api/v1/agents/{agentId}/messages 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.ai 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: analytics description: Sales performance across marketplaces x-group: Analytics - name: aops description: Agent operating procedures x-group: AOPs - name: branding description: branding x-group: Branding - name: campaigns description: Campaign briefs, offer windows, and marketplace runs x-group: Campaigns - name: catalog description: catalog x-group: Catalog - name: commerce description: commerce x-group: Commerce - name: developer-platform description: Authenticated developer platform APIs x-group: Developer Platform - name: documents description: Knowledge base document uploads x-group: Knowledge Base - name: follow-ups description: follow-ups x-group: Follow Ups - name: inventory description: Inventory quantities, planning signals, and marketplace listing absence x-group: Inventory - 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: reviews description: Marketplace product reviews and seller replies x-group: Reviews - name: scripts description: scripts x-group: Scripts - name: settlements description: settlements x-group: Settlements - name: ucp description: Universal Commerce Protocol x-group: UCP paths: /api/v1/agents/{agentId}/messages: post: tags: - agents summary: Send a message to an agent description: >- Message the exact built-in or custom agent in the URL, using its saved model, instructions, tools, permissions and Programmatic starting mode. ### Authentication Requires an API key with `agents:invoke`, or a sign-in session. Organization-owned keys use their recorded creator's current membership and agent access; keys without a valid owner are refused. API keys identify their organization; session requests include `organizationId`. ### Conversation and execution - The same caller, agent and `clientThreadKey` continue one conversation. Different callers, agents and organizations are isolated. - No model, prompt or tool overrides are accepted. - `wait=false` queues durable work and returns 202; `wait=true` returns the final reply or pending approvals. - Send `decisions` with the same `clientThreadKey` to approve or reject a paused run. operationId: post_v1_agents_by_agentid_messages parameters: - name: agentId in: path required: true schema: type: string requestBody: required: true content: application/json: schema: type: object properties: organizationId: type: string minLength: 1 maxLength: 120 message: type: string minLength: 1 maxLength: 100000 clientThreadKey: default: default type: string minLength: 1 maxLength: 200 wait: default: false type: boolean decisions: minItems: 1 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: message: Summarize today's orders. clientThreadKey: daily-report wait: true responses: '200': description: The agent's verbatim final reply or pending approvals. content: application/json: schema: type: object properties: agentId: type: string threadKey: type: string runId: type: string threadId: type: string status: type: string enum: - accepted - running - completed - awaiting_approval - failed reply: anyOf: - type: string - 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 additionalProperties: false - type: 'null' error: anyOf: - type: string - type: 'null' required: - agentId - threadKey - runId - threadId - status - reply - approvals - error additionalProperties: false '202': description: Accepted for durable execution. content: application/json: schema: type: object properties: agentId: type: string threadKey: type: string runId: type: string threadId: type: string status: type: string enum: - accepted - running - completed - awaiting_approval - failed reply: anyOf: - type: string - 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 additionalProperties: false - type: 'null' error: anyOf: - type: string - type: 'null' required: - agentId - threadKey - runId - threadId - status - reply - approvals - error additionalProperties: false headers: Location: description: Caller-scoped status URL for this agent's run. schema: type: string format: uri-reference Retry-After: description: Seconds to wait before reading an open run again. schema: type: integer minimum: 1 '400': description: Invalid message, decisions or organization scope. '401': description: A valid Bearer API key or sign-in session is required. '402': description: Insufficient AI credits. '403': description: >- Missing agents:invoke scope, inactive agent, revoked key, or the credential owner lacks organization membership or agent sharing access. '404': description: The run does not belong to this agent and caller. '409': description: >- This conversation already has an active run, or there is no matching pending approval. '500': description: The agent run failed. '504': description: The waiting request timed out. The error includes the stored run ID. 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.