Agent Threads

Threads are conversations between users and agents. Each thread holds an ordered message history and, when RBAC is enabled, is bound to the role that created it.

Create Thread

POST /v1/workspaces/{workspaceId}/agent/threads

Request Body

FieldTypeRequiredDescription
titlestringYesDisplay title for the thread
spaceIdUUIDNoBind the thread to a space (must belong to the workspace)
userIdUUIDNoThe Sharely user this thread belongs to
temporalUserIdstringNoAnonymous/temporal user identifier
agentServerIdstringNoBind the thread to a registered agent server

Example Request

curl -X POST \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/threads' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "Support conversation",
    "agentServerId": "9f6c1e2a-..."
  }'

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Support conversation",
  "status": "ACTIVE",
  "spaceId": null,
  "userId": null,
  "temporalUserId": null,
  "agentServerId": "9f6c1e2a-...",
  "roleId": null,
  "createdAt": "2026-06-11T10:00:00.000Z",
  "updatedAt": "2026-06-11T10:00:00.000Z",
  "deletedAt": null
}

When workspace RBAC is enabled, roleId is automatically set from the calling token's role.

Errors

  • 400 - spaceId does not belong to the workspace
  • 401 - RBAC is enabled but the token carries no role
  • 404 - Workspace not found

List Threads

GET /v1/workspaces/{workspaceId}/agent/threads

Query Parameters

ParameterTypeRequiredDescription
spaceIdUUIDNoFilter by space
userIdUUIDNoFilter by user
temporalUserIdstringNoFilter by anonymous/temporal user
cursorUUIDNoPagination cursor from a previous response's nextCursor
limitnumberNoPage size. Min 1, max 50, default 20

Results are ordered by updatedAt descending (most recently active first). When RBAC is enabled, only threads bound to the token's role are returned.

Example Request

curl 'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/threads?limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (200 OK)

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Support conversation",
      "status": "ACTIVE",
      "spaceId": null,
      "userId": null,
      "temporalUserId": null,
      "agentServerId": "9f6c1e2a-...",
      "createdAt": "2026-06-11T10:00:00.000Z",
      "updatedAt": "2026-06-11T10:05:12.000Z",
      "_count": { "messages": 6 }
    }
  ],
  "nextCursor": "3f1d9a40-...",
  "hasMore": true
}

Pass nextCursor as the cursor query parameter to fetch the next page. nextCursor is null on the last page.

Get Thread

GET /v1/workspaces/{workspaceId}/agent/threads/{threadId}

Returns the thread with its full message history, ordered oldest-first.

Example Request

curl 'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/threads/{threadId}' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response (200 OK)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Support conversation",
  "status": "ACTIVE",
  "spaceId": null,
  "userId": null,
  "temporalUserId": null,
  "agentServerId": "9f6c1e2a-...",
  "roleId": null,
  "messages": [
    {
      "id": "a1b2c3d4-...",
      "role": "user",
      "content": "How do refunds work?",
      "thinkingSteps": [],
      "toolCalls": [],
      "sources": [],
      "tokenUsage": null,
      "model": null,
      "finishReason": null,
      "metadata": null,
      "createdAt": "2026-06-11T10:00:05.000Z",
      "updatedAt": "2026-06-11T10:00:05.000Z",
      "deletedAt": null
    },
    {
      "id": "e5f6a7b8-...",
      "role": "assistant",
      "content": "Refunds are processed within 5 business days...",
      "thinkingSteps": [{ "thinkingId": "t1", "title": "Searching workspace knowledge", "content": "Found 5 passages", "status": "completed", "durationMs": 850 }],
      "toolCalls": [{ "id": "tc1", "name": "semantic_search", "input": { "text": "refund policy" } }],
      "sources": [{ "id": "knowledge-uuid", "type": "semantic", "title": "Refund Policy", "snippet": "..." }],
      "tokenUsage": { "inputTokens": 1200, "outputTokens": 240, "totalTokens": 1440 },
      "model": "claude-sonnet-4-5",
      "finishReason": "stop",
      "metadata": null,
      "createdAt": "2026-06-11T10:00:09.000Z",
      "updatedAt": "2026-06-11T10:00:09.000Z",
      "deletedAt": null
    }
  ],
  "createdAt": "2026-06-11T10:00:00.000Z",
  "updatedAt": "2026-06-11T10:00:09.000Z",
  "deletedAt": null
}

Errors

  • 404 - Thread not found or does not belong to the workspace
  • RBAC: a token whose role does not match the thread's role cannot read it

Related