Agent API

The Agent API (also called the Agent Backplane) is the REST surface that custom agents use to integrate with Sharely.ai. It provides conversation threads, message persistence, role-scoped retrieval (RAG), agent server registration, and first-party tool execution.

If you're building a custom agent in TypeScript, the open-source Sharely Server SDK wraps this API for you — the SDK's threads.* and rag() client methods map one-to-one onto these endpoints. Use the raw API directly when integrating from other languages or when you need lower-level control.

Base URL

https://api.sharely.ai/v1/workspaces/{workspaceId}/agent

Authentication

All Agent API endpoints require Bearer token authentication:

Authorization: Bearer YOUR_ACCESS_TOKEN

See the Authentication guide for obtaining access tokens from your API key. When workspace RBAC is enabled, the token's role determines what threads and knowledge each call can see — see RBAC behavior below.

Endpoints

Threads

  • Create Thread - POST /v1/workspaces/{workspaceId}/agent/threads
  • List Threads - GET /v1/workspaces/{workspaceId}/agent/threads
  • Get Thread - GET /v1/workspaces/{workspaceId}/agent/threads/{threadId}

Messages

  • Store Message - POST /v1/workspaces/{workspaceId}/agent/threads/{threadId}/messages

Retrieval

  • RAG Query - POST /v1/workspaces/{workspaceId}/agent/rag

Agent Servers

Tools

  • Execute Tool - POST /v1/workspaces/{workspaceId}/agent/tools/{name}/execute

Core Concepts

Threads and Messages

A thread is one conversation between a user and an agent. Messages on a thread carry not just text but the full agent turn: thinking steps, tool calls, sources (citations), token usage, model, and finish reason. This is the same shape the Server SDK wire protocol reduces to.

Agent Servers

An agent server is a registration record that tells Sharely.ai where your custom agent is hosted (name + url). Threads can be bound to an agent server, and the platform dispatches chat turns for those threads to your server.

RBAC Behavior

When the workspace has RBAC enabled (rbacStatus: "ACTIVE"):

  • Tokens must carry a role; threads are automatically bound to the creating token's role
  • Listing and reading threads is filtered to the token's role
  • RAG results only include knowledge assigned to the token's role

When RBAC is inactive, these filters do not apply.

Typical Flow

# 1. Create a thread for a user conversation
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" }'
 
# 2. Store the user's message
curl -X POST 'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/threads/{threadId}/messages' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "id": "GENERATED-UUID", "role": "user", "content": "How do refunds work?" }'
 
# 3. Retrieve role-scoped context
curl -X POST 'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/rag' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{ "text": "refund policy", "topK": 5 }'
 
# 4. Run your agent, then store the assistant message with the full turn
curl -X POST 'https://api.sharely.ai/v1/workspaces/{workspaceId}/agent/threads/{threadId}/messages' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "GENERATED-UUID",
    "role": "assistant",
    "content": "Refunds are processed within 5 business days...",
    "sources": [{ "id": "knowledge-uuid", "type": "semantic", "title": "Refund Policy", "snippet": "..." }],
    "model": "claude-sonnet-4-5",
    "finishReason": "stop",
    "tokenUsage": { "inputTokens": 1200, "outputTokens": 240, "totalTokens": 1440 }
  }'

Related Documentation