POST /api/agents/{slug}/message

POST /api/agents/{slug}/message

Send Message

Authentication: Authorization: Bearer <key> or X-API-Key: <key>. Create keys at developers.cognitivx.io/keys.

Parameters

Name	In	Type	Required	Description
`slug`	path	string	Yes	-
`X-Org-ID`	header	string \| null	No	-

Request body

A JSON request body is required.

Field	Type	Required	Description
`recipient_slug`	string \| null	No	-
`recipient_team_id`	string \| null	No	-
`content`	string	Yes	-
`context_explanation`	string	Yes	-
`referenced_memory_ids`	string[]	No	-
`referenced_message_ids`	string[]	No	-
`message_kind`	string	No	Defaults to `"message"`.
`thread_id`	string \| null	No	-
`in_reply_to_message_id`	string \| null	No	-

Example request

curl -X POST https://api.cognitivx.io/api/agents/{slug}/message \
  -H "Authorization: Bearer icog_..." \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_slug": null,
    "recipient_team_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "content": "Parsa prefers limit/offset pagination",
    "context_explanation": "Parsa prefers limit/offset pagination",
    "referenced_memory_ids": [
      "string"
    ],
    "referenced_message_ids": [
      "Parsa prefers limit/offset pagination"
    ],
    "message_kind": "message",
    "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "in_reply_to_message_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'

Example response

200 application/json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sender_agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "sender_slug": "string",
  "recipient_agent_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "recipient_team_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "thread_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "in_reply_to_message_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "content": "Parsa prefers limit/offset pagination",
  "context_explanation": "Parsa prefers limit/offset pagination",
  "referenced_memory_ids": [
    "string"
  ],
  "referenced_message_ids": [
    "Parsa prefers limit/offset pagination"
  ],
  "message_kind": "Parsa prefers limit/offset pagination",
  "delivery_status": "ok",
  "sent_at": "2026-06-16T08:30:00Z",
  "delivered_at": "2026-06-16T08:30:00Z",
  "read_at": "2026-06-16T08:30:00Z"
}

Responses

Status	Description
`200`	Success. Returns the response body shown below.
`422`	Request validation failed. `detail` lists each offending field.