Chats API

HTTP reference for chat sessions — list, create, rename, archive, share, and the operations recorded inside each conversation.

All paths are relative to https://api.aleex-rank.ai/api/v2 and authenticate with X-API-Key: rk_... (see REST API). Successful responses use the standard {"success": true, "data": {...}} envelope.

A chat is a persistent conversation container. It does not, by itself, exchange messages: you send a prompt and read the answer by opening a stream on the agent backend, and you persist context across turns by passing the chat’s id as chat_id on that stream — see Chat & pentest execution, Streaming and the Chat surface. This page documents only the chat-session resource: creating, listing, renaming, archiving, sharing, and inspecting the operations a chat has accumulated. The SDK mirrors every endpoint here as client.chats.* — see SDK resources.

Chats

GET    /chats
POST   /chats
GET    /chats/mine
GET    /chats/shared
GET    /chats/{id}
PUT    /chats/{id}
DELETE /chats/{id}

GET /chats returns your own chats and the chats shared with your teams in one response, split by type. GET /chats/mine and GET /chats/shared return a single paginated list each. All three accept page, per_page and include_archived (default false).

GET /chats keeps the two collections separate and reports a count for each:

{
  "success": true,
  "data": {
    "own_chats": [
      {
        "id": 14,
        "nombre": "Apache CVE research",
        "user_id": 42,
        "owner_username": "alice",
        "archived": false,
        "total_operations": 7,
        "shared_teams": [{"id": 4, "name": "Security Team"}],
        "created_at": "2026-01-12 17:47:16",
        "last_updated_at": "2026-01-14 09:02:51"
      }
    ],
    "shared_chats": [],
    "totals": {"own": 12, "shared": 3},
    "page": 1,
    "per_page": 20
  }
}

GET /chats/mine and GET /chats/shared return the paginated form with an items array and a pagination block:

{
  "success": true,
  "data": {
    "items": [
      {
        "id": 14,
        "nombre": "Apache CVE research",
        "user_id": 42,
        "owner_username": "alice",
        "archived": false,
        "total_operations": 7,
        "shared_teams": [{"id": 4, "name": "Security Team"}],
        "created_at": "2026-01-12 17:47:16",
        "last_updated_at": "2026-01-14 09:02:51"
      }
    ],
    "pagination": {"total": 12, "count": 12, "per_page": 20, "current_page": 1, "total_pages": 1}
  }
}

Create a chat. The name field is nombre (the SDK exposes it as name); it is required:

{"nombre": "Apache CVE research"}

Creation returns the new chat object inside data with HTTP 201. GET /chats/{id} returns the same object. Rename with PUT /chats/{id} (the body is again nombre):

{"nombre": "Renamed session"}

DELETE /chats/{id} soft-deletes the chat — it unshares it from every team and soft-deletes its operations first:

{"success": true, "data": {"success": true, "message": "Chat deleted successfully"}}

Listing, retrieving and the operations endpoints are open to the owner and to members of any team the chat is shared with; renaming, deleting, archiving and sharing are owner-only.

Operations

Every time an agent returns a response, that exchange is recorded as an operation — the input/output token counts and computed cost it carries are the unit billing rolls up (see the Operation concept in Agents, tools & MCP). A chat’s operations are the turns of its conversation, and total_operations on the chat object counts them.

GET    /chats/{id}/operations
POST   /chats/{id}/operations
DELETE /chats/{id}/operations/{operationId}

GET /chats/{id}/operations is paginated (page, per_page) and lists each turn newest-first:

{
  "success": true,
  "data": {
    "items": [
      {
        "relation_id": 88,
        "chat_id": 14,
        "operation_id": 531,
        "user_id": 42,
        "username": "alice",
        "prompt": "Summarize the latest critical Apache CVEs.",
        "answer": "The most relevant disclosures this month are ...",
        "created_at": "2026-01-14 09:02:51"
      }
    ],
    "pagination": {"total": 7, "count": 7, "per_page": 20, "current_page": 1, "total_pages": 1}
  }
}

Attach one or more existing operations to a chat with operation — a single id or an array of ids. Every id must belong to you:

{"operation": [531, 532]}

{
  "success": true,
  "data": {
    "success": true,
    "message": "Operations assigned successfully",
    "chat_id": 14,
    "assigned_operations": [531, 532],
    "total_operations": 9
  }
}

DELETE /chats/{id}/operations/{operationId} soft-deletes a single operation from the chat. You can detach an operation if you own it or you own the chat.

Archiving

Archiving hides a chat from the default listings without deleting it; pass include_archived=true to the list endpoints to see archived chats. Both actions are owner-only.

PATCH /chats/{id}/archive
PATCH /chats/{id}/unarchive

{"success": true, "data": {"success": true, "message": "Chat archived successfully"}}

Sharing

A chat can be shared with multiple teams you belong to; members of those teams then see it under GET /chats/shared. Sharing, like the other write actions, is owner-only.

POST   /chats/{id}/share
DELETE /chats/{id}/share
DELETE /chats/{id}/share/all

Share with a team by id:

{"team_id": 4}

The response echoes every team the chat is now shared with:

{
  "success": true,
  "data": {
    "success": true,
    "message": "Chat shared with team successfully",
    "shared_teams": [
      {"id": 4, "name": "Security Team", "description": "Internal red team"}
    ]
  }
}

DELETE /chats/{id}/share unshares from a single team (it takes the same {"team_id": 4} body); DELETE /chats/{id}/share/all unshares from every team at once. For the teams, roles and membership that govern who can see a shared chat, see Teams API.