Conversations

The Conversations API stores and retrieves agent conversation history. Messages are indexed for full-text search using FTS5. Longer conversation histories can be summarized and then drilled into on demand.

Base path: /api/conversations

All endpoints require Authorization: Bearer <token>.

---

Store Message

Persists a single conversation message.

POST /api/conversations/store

Request body:

{
  "agentId": "backend-coder",
  "role": "assistant",
  "content": "I've implemented the pagination utility in src/lib/paginate.ts",
  "sessionId": "sess_01J...",
  "taskId": "tk_01J...",
  "metadata": {
    "model": "claude-sonnet-4-6",
    "tokensUsed": 842
  }
}

Field	Type	Required	Description
agentId	string	Yes	Agent name or ID this message belongs to
role	string	Yes	user, assistant, or system
content	string	Yes	Message text
sessionId	string	No	Session grouping identifier
taskId	string	No	Associated task ID
metadata	object	No	Model info, token counts, etc.

Response: 201 Created

{
  "success": true,
  "data": {
    "id": "msg_01J...",
    "agentId": "backend-coder",
    "role": "assistant",
    "sessionId": "sess_01J...",
    "createdAt": "2026-04-03T12:01:00Z"
  }
}

curl:

curl -X POST "https://api.cortex.acrobi.com/api/conversations/store" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "backend-coder",
    "role": "assistant",
    "content": "I have implemented the pagination utility",
    "sessionId": "sess_01J..."
  }'

---

Search Conversations

Full-text search over conversation content using FTS5.

GET /api/conversations/search

Query parameters:

Parameter	Type	Required	Description
q	string	Yes	Search query
agentId	string	No	Restrict to a specific agent
role	string	No	user, assistant, or system
sessionId	string	No	Restrict to a session
since	string	No	ISO 8601 timestamp — only messages after this
limit	number	No	Default 20, max 100
offset	number	No	Default 0

Response:

{
  "success": true,
  "data": [
    {
      "id": "msg_01J...",
      "agentId": "backend-coder",
      "role": "assistant",
      "content": "I've implemented the pagination utility in src/lib/paginate.ts",
      "score": 0.92,
      "sessionId": "sess_01J...",
      "taskId": "tk_01J...",
      "createdAt": "2026-04-03T12:01:00Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 3 }
}

curl:

curl "https://api.cortex.acrobi.com/api/conversations/search?q=pagination+utility&agentId=backend-coder" \
  -H "Authorization: Bearer <token>"

---

List Conversations for Agent

Returns paginated message history for a specific agent, ordered by most recent first.

GET /api/conversations/:agentId

Query parameters:

Parameter	Type	Description
sessionId	string	Filter to a specific session
taskId	string	Filter to messages for a task
role	string	Filter by role
limit	number	Default 50, max 200
offset	number	Default 0

Response:

{
  "success": true,
  "data": [
    {
      "id": "msg_01J...",
      "role": "user",
      "content": "Implement pagination for the agents list endpoint",
      "sessionId": "sess_01J...",
      "taskId": "tk_01J...",
      "metadata": null,
      "createdAt": "2026-04-03T12:00:00Z"
    },
    {
      "id": "msg_02J...",
      "role": "assistant",
      "content": "I've implemented the pagination utility...",
      "sessionId": "sess_01J...",
      "taskId": "tk_01J...",
      "metadata": { "model": "claude-sonnet-4-6", "tokensUsed": 842 },
      "createdAt": "2026-04-03T12:01:00Z"
    }
  ],
  "pagination": { "limit": 50, "offset": 0, "total": 284 }
}

curl:

curl "https://api.cortex.acrobi.com/api/conversations/backend-coder?limit=20" \
  -H "Authorization: Bearer <token>"

---

Conversation Overview

Returns a summary of the agent's conversation activity — total messages, sessions, time range, and top topics.

GET /api/conversations/:agentId/overview

Response:

{
  "success": true,
  "data": {
    "agentId": "backend-coder",
    "totalMessages": 284,
    "totalSessions": 31,
    "firstMessageAt": "2026-01-15T09:00:00Z",
    "lastMessageAt": "2026-04-03T12:01:00Z",
    "roleBreakdown": {
      "user": 102,
      "assistant": 178,
      "system": 4
    },
    "recentSessions": [
      {
        "sessionId": "sess_01J...",
        "messageCount": 12,
        "startedAt": "2026-04-03T12:00:00Z",
        "summary": "Implemented pagination for agents list"
      }
    ]
  }
}

---

Expand Conversation Summary

When a session has been condensed into a summary (to save context window), this endpoint retrieves the full turn-by-turn expansion.

GET /api/conversations/:agentId/expand

Query parameters:

Parameter	Type	Required	Description
sessionId	string	Yes	Session to expand
limit	number	No	Max turns to return (default 100)

Response:

{
  "success": true,
  "data": {
    "sessionId": "sess_01J...",
    "agentId": "backend-coder",
    "summary": "Implemented pagination for agents list",
    "messages": [
      {
        "id": "msg_01J...",
        "role": "user",
        "content": "Implement pagination for the agents list endpoint",
        "createdAt": "2026-04-03T12:00:00Z"
      },
      {
        "id": "msg_02J...",
        "role": "assistant",
        "content": "I've implemented the pagination utility...",
        "createdAt": "2026-04-03T12:01:00Z"
      }
    ]
  }
}