---
title: "Send a product-discovery message"
method: POST
path: "/v1/a2a/{key}/{domain}"
tags: ["Agent to agent"]
---

# Send a product-discovery message

`POST /v1/a2a/{key}/{domain}`

## Request

- Base URL: `https://agent.cnstrc.com`
- URL: `https://agent.cnstrc.com/v1/a2a/{key}/{domain}`
- Auth: HTTP bearer

**🔐 This endpoint requires [HTTP Bearer authentication](https://docs.constructor.com/reference/main-authentication#bearer-authentication).**

Send one blocking A2A 1.0 `SendMessage` turn to a configured AI Shopping Agent domain. This endpoint uses the same per-domain A2A opt-in as the public agent card and requires a Constructor bearer token authorized for the company that owns the requested index key. Reuse the same `contextId` for later turns in the same conversation. The response is a terminal A2A task containing `text/plain` parts and, when accepted by the caller, `application/json` structured event parts. Streaming, push notifications, deferred execution, and task-management methods are not supported.

## Path parameters

- `key` string, required
- `domain` string, required

## Headers

- `A2A-Version` '1.0', required

## Request body

- A2ASendMessageRequest: A2A 1.0 JSON-RPC request for one blocking SendMessage turn.
  - `jsonrpc` '2.0', required: JSON-RPC protocol version.
  - `id` union, required: Caller-supplied request identifier echoed in the response.
    - string
    - integer
  - `method` 'SendMessage', required: JSON-RPC method name for a blocking A2A message turn.
  - `params` A2ASendMessageParameters, required: Parameters of the A2A `SendMessage` method. Send only the fields listed in `params`, `message`, `configuration`, and each message part. A field that is not in the A2A 1.0 `SendMessage` request returns an InvalidParams JSON-RPC error (`-32602`). Put extra caller data in `metadata`.
    - `message` A2AUserMessage, required: User-originated A2A message submitted to the agent.
      - `messageId` string, required: Caller-generated identifier for this message.
      - `contextId` string: Caller-owned conversation identifier. Reuse it for later turns in the same conversation.
      - `taskId` string: Not supported. Any value returns a TaskNotFound JSON-RPC error (`-32001`). Leave out `taskId` and reuse `contextId` for follow-up turns.
      - `role` 'ROLE_USER', required: Fixed role identifier for user-originated messages.
      - `parts` A2AUserTextPart[], required: Content parts that make up the user message.
        - `text` string, required: Plain-text content of the user message part.
        - `mediaType` string: Media type of the text. Omit it or use `text/plain`. Any other media type returns a rejected task.
        - `metadata` object: Optional caller-defined data for this part. The agent accepts it but does not use it.
      - `metadata` object: Optional caller-defined data for this message. The agent accepts it but does not use it.
    - `configuration` A2ASendMessageConfiguration: Optional response-format preferences for a SendMessage request.
      - `acceptedOutputModes` string[]: Media types the caller can consume. Supported values are `text/plain`, `application/json`, `text/*`, `application/*`, and `*/*`; media type parameters are ignored. When omitted or empty, the agent may return both supported modes.
      - `returnImmediately` false: Deferred execution is not supported. Omit this field or set it to `false`; `true` returns an InvalidParams JSON-RPC error.
    - `metadata` object: Optional caller-defined data for this request. The agent accepts it but does not use it.

## Response `200`

A JSON-RPC success or protocol-error response. Successful calls return a terminal A2A task.

- union: JSON-RPC response containing either a `result` on success or an `error` on failure.
  - A2ASendMessageSuccess: Successful JSON-RPC response containing the completed A2A task.
    - `jsonrpc` '2.0', required: JSON-RPC protocol version.
    - `id` union, required: Caller-supplied JSON-RPC request identifier echoed in the response.
      - string
      - integer
    - `result` object, required: Successful SendMessage result.
      - `task` A2ATask, required: A2A task for one finished AI Shopping Agent turn.
        - `id` string, required: Server-generated identifier for the task.
        - `contextId` string, required: Conversation identifier for the task. It matches the request `contextId`, or the server creates one when the request leaves it out.
        - `status` A2ATaskStatus, required: Terminal processing state and optional agent message for an A2A task.
          - `state` 'TASK_STATE_COMPLETED' | 'TASK_STATE_REJECTED' | 'TASK_STATE_FAILED', required: `TASK_STATE_COMPLETED` means the agent produced a result, `TASK_STATE_REJECTED` means it declined the message, and `TASK_STATE_FAILED` means processing failed.
          - `message` A2AAgentMessage: Agent-originated A2A message attached to a task status.
            - `messageId` string, required: Server-generated identifier for this agent message.
            - `contextId` string: Conversation identifier of the task this message belongs to.
            - `taskId` string: Identifier of the task this message belongs to.
            - `role` 'ROLE_AGENT', required: Fixed role identifier for agent-originated messages.
            - `parts` A2ATextPart[], required: Content parts that make up the agent response message.
              - …
          - `timestamp` string, date-time: ISO 8601 date-time at which the task entered this state.
        - `artifacts` A2AArtifact[]: Response artifacts produced when the task completes successfully.
          - `artifactId` string, required: Server-generated identifier for the response artifact.
          - `name` string: Human-readable name of the artifact.
          - `parts` union[], required: Text and structured event parts in the artifact.
            - union
              - …
  - A2AJSONRPCErrorResponse: JSON-RPC protocol or processing error response.
    - `jsonrpc` '2.0', required: JSON-RPC protocol version.
    - `id` union: Caller-supplied JSON-RPC request identifier echoed in the response.
      - string
      - integer
    - `error` object, required: JSON-RPC error details.
      - `code` integer, required: JSON-RPC error code.
      - `message` string, required: Human-readable JSON-RPC error summary.
      - `data` unknown

## Other responses

- `401`: The bearer token is missing, invalid, or expired.
- `403`: The bearer token is valid but is not authorized for the company that owns the requested index key.
- `404`: The index or domain is unknown, A2A is not enabled for the domain, or public agent hosting is unavailable.
- `429`: Rate limit exceeded.
- `503`: The authentication service or tenant key-ownership lookup is unavailable.

---

[API](https://skmtc.dev/constructor/apis/ai-shopping-agent.md) - [All operations](https://skmtc.dev/constructor/apis/ai-shopping-agent/llms.txt) - [OpenAPI document](https://skmtc.dev/constructor/apis/ai-shopping-agent/revisions/dbdbd16abddd?raw)