API Endpoints

This page is the route map for the current backend API.

Use it when you already know what part of the product you are touching and need the exact path, auth expectation, or response shape.

All REST endpoints are versioned under /v1/. Successful mutations with no response body return 204 No Content. JSON field names use snake_case.

How To Read This Page

The table near the top is the quickest way to find a route.

The sections below it add more detail:

• public endpoints first
• then auth and user endpoints
• then workspace, agent, conversation, integration, notification, and support endpoints
• realtime (Socket.IO) at the end

If you are new, start with the endpoint summary and the response envelope, then jump only to the section you need.

Endpoint Summary

Method	Path	Auth	Description
GET	/v1/health	—	Health check
GET	/v1/legal	—	Legal documents
POST	/v1/fcm-token	Yes	Save push token
POST	/v1/auth/sign-in	Yes	Sign in
POST	/v1/auth/sign-up	Yes	Sign up
DELETE	/v1/auth/delete	Yes	Delete account
GET	/v1/users/profile	Yes	Get user profile
PATCH	/v1/users	Yes	Update user profile
GET	/v1/users/legal	Yes	Get user legal status
POST	/v1/users/legal/accept	Yes	Accept legal documents
GET	/v1/workspaces	Yes	List workspaces
GET	/v1/workspaces/{id}	Yes	Get workspace
POST	/v1/workspaces	Yes	Create workspace
PATCH	/v1/workspaces/{id}	Yes	Update workspace
DELETE	/v1/workspaces/{id}	Yes	Delete workspace
GET	/v1/workspaces/{workspaceId}/agents	Yes	List agents in workspace
GET	/v1/agents/{id}	Yes	Get agent
GET	/v1/agents/{id}/details	Yes	Get agent details
GET	/v1/agents/{id}/history	Yes	Get agent conversation history
GET	/v1/agents/{id}/settings	Yes	Get agent settings
GET	/v1/workspaces/{workspaceId}/conversations	Yes	List conversations
GET	/v1/workspaces/{workspaceId}/conversations/{id}	Yes	Get conversation
GET	/v1/workspaces/{workspaceId}/conversations/{id}/messages	Yes	List messages
POST	/v1/workspaces/{workspaceId}/conversations/{id}/messages	Yes	Send message
POST	/v1/workspaces/{workspaceId}/messages/{id}/action	Yes	Respond to action card
GET	/v1/integrations	Yes	List tools and integrations
POST	/v1/integrations/connect	Yes	Get OAuth config
POST	/v1/integrations/callback	Yes	Send OAuth auth code
GET	/v1/integrations/{provider}/accounts	Yes	List connected accounts
DELETE	/v1/integrations/{provider}/accounts/{accountId}	Yes	Disconnect account
PATCH	/v1/tools/{name}	Yes	Toggle tool
GET	/v1/notifications	Yes	List notifications
POST	/v1/notifications/{id}/read	Yes	Mark notification read
POST	/v1/notifications/read-all	Yes	Mark all notifications read
GET	/v1/notifications/preferences	Yes	Get notification preferences
PATCH	/v1/notifications/preferences	Yes	Update notification preferences
POST	/v1/support/ticket	Yes	Submit support ticket
WS	/socket.io/ (/v1 namespace)	Yes	Realtime Socket.IO transport

Response Envelope

Most successful REST responses are wrapped in a data envelope:

{ "data": { ... } }

Mutations that produce no body return 204 No Content.

Error Response

Errors are returned as a structured object:

{
  "message": "string",
  "code": "string",
  "extra": {}
}

extra may be null when no additional context is available.

Common Enums

Enum	Values
RuntimeStatus	provisioning, ready, offline, failed
RuntimePhase	Pending, Progressing, Ready, Error
AgentStatus	online, busy, pending, error, offline
AgentSkill	web_search, analysis, fact_check, news, sources, coding, writing, translation, summarization, planning
AgentModel	flash, sonnet, opus
ResponseLength	auto, short, medium, long
ConversationType	swarm, agent
MessageRole	user, agent, system
MessageStatus	pending, delivered, failed
MessageContentType	text, action_card, tool_status, system, loading
AttachmentType	image, video, audio, file
ActionStyle	primary, secondary, destructive
ToolState	running, completed, failed
IntegrationItemType	tool, app
IntegrationProvider	google_calendar, gmail, slack, jira, notion, asana, github, zoom
NotificationType	agentMessage, systemAlert, workspaceUpdate

Core

GET /v1/health

No authentication.

{ "data": { "online": true, "version": "1.0.0" } }

GET /v1/legal

No authentication. Returns the current legal document content and versions.

{
  "data": {
    "terms_of_service": "string",
    "privacy_policy": "string",
    "has_agreed_with_terms": false,
    "has_agreed_with_privacy_policy": false,
    "terms_of_service_version": "string",
    "privacy_policy_version": "string"
  }
}

POST /v1/fcm-token

Saves the device push token for Firebase Cloud Messaging.

Request:

{ "push_token": "string" }

Response:

{ "success": true }

Authentication

All auth endpoints require a Firebase ID token in the X-Token header.

POST /v1/auth/sign-in

No body. Response: 204 No Content.

POST /v1/auth/sign-up

No body. Response: 204 No Content.

DELETE /v1/auth/delete

Request:

{ "reason": "string", "description": "string" }

Response: 204 No Content.

User

GET /v1/users/profile

Returns the authenticated user's full profile.

{
  "data": {
    "email": "string",
    "firebase_uid": "string",
    "nickname": "string",
    "name": "string",
    "surname": "string",
    "avatar_url": "string",
    "country_code": "string",
    "date_of_birth": "ISO8601 | null",
    "created_at": "ISO8601",
    "is_deleted": false,
    "is_banned": false,
    "has_agreed_with_terms": false,
    "has_agreed_with_privacy_policy": false,
    "preferences": {
      "platform_theme": "string",
      "platform_language": "string",
      "currency_code": "string"
    },
    "subscription": {
      "name": "string",
      "code": "string",
      "expires_at": "ISO8601 | null"
    }
  }
}

PATCH /v1/users

All fields optional. Response: 204 No Content.

{
  "nickname": "string",
  "country_code": "string",
  "surname": "string",
  "name": "string",
  "date_of_birth": "ISO8601",
  "preferences": {
    "platform_theme": "string",
    "platform_language": "string",
    "currency_code": "string"
  }
}

GET /v1/users/legal

Returns the current legal document versions plus the user's acceptance state.

{
  "data": {
    "terms_of_service": "string",
    "privacy_policy": "string",
    "has_agreed_with_terms": false,
    "has_agreed_with_privacy_policy": false,
    "terms_of_service_version": "string",
    "privacy_policy_version": "string"
  }
}

POST /v1/users/legal/accept

Accepts one or both legal document versions. All fields optional.

Request:

{
  "terms_of_service_version": "string",
  "privacy_policy_version": "string"
}

Response: 204 No Content.

Workspaces

Each workspace response includes a runtime object representing the current swarm status.

Workspace shape:

{
  "id": "string",
  "name": "string",
  "created_at": "ISO8601",
  "updated_at": "ISO8601",
  "runtime": {
    "status": "provisioning | ready | offline | failed",
    "phase": "Pending | Progressing | Ready | Error",
    "verified": false,
    "total_agents": 0,
    "last_message_preview": {
      "text": "string",
      "sender_name": "string",
      "timestamp": "ISO8601"
    }
  }
}

GET /v1/workspaces

Returns all workspaces owned by the authenticated user.

{ "data": [ ...workspaces ] }

GET /v1/workspaces/{id}

Returns a single workspace by ID.

{ "data": workspace }

POST /v1/workspaces

Creates a new workspace.

Request:

{ "name": "string" }

Response:

{ "data": workspace }

PATCH /v1/workspaces/{id}

Updates workspace properties. All fields optional.

Request:

{ "name": "string" }

Response: 204 No Content.

DELETE /v1/workspaces/{id}

Deletes a workspace permanently.

Response: 204 No Content.

Agents

GET /v1/workspaces/{workspaceId}/agents

Returns all agents belonging to the workspace.

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "role": "string",
      "slug": "string",
      "avatar": "string",
      "status": "online | busy | pending | error | offline"
    }
  ]
}

GET /v1/agents/{id}

Returns a single agent summary (same shape as the list item above).

{
  "data": {
    "id": "string",
    "name": "string",
    "role": "string",
    "slug": "string",
    "avatar": "string",
    "status": "online | busy | pending | error | offline"
  }
}

GET /v1/agents/{id}/details

Returns the full agent profile including skills and stats.

{
  "data": {
    "id": "string",
    "workspace_id": "string",
    "name": "string",
    "role": "string",
    "slug": "string",
    "created_at": "ISO8601",
    "updated_at": "ISO8601 | null",
    "description": "string",
    "avatar_url": "string",
    "status": "online | busy | pending | error | offline",
    "sort_order": 0,
    "skills": [
      "web_search",
      "analysis",
      "fact_check",
      "news",
      "sources",
      "coding",
      "writing",
      "translation",
      "summarization",
      "planning"
    ],
    "stats": {
      "total_messages": 0,
      "memory_used_pct": 0
    }
  }
}

GET /v1/agents/{id}/history

Returns the agent's past conversation summaries. Supports offset-based pagination.

Query params: limit (int), offset (int)

{
  "items": [
    {
      "conversation_id": "string",
      "title": "string",
      "subtitle": "string",
      "created_at": "ISO8601 | null"
    }
  ]
}

GET /v1/agents/{id}/settings

Returns the agent's model configuration and available system prompts.

{
  "data": {
    "model": "flash | sonnet | opus",
    "response_length": "auto | short | medium | long",
    "prompts": [
      {
        "id": "string",
        "name": "string",
        "description": "string",
        "content": "string"
      }
    ]
  }
}

Conversations and Messages

GET /v1/workspaces/{workspaceId}/conversations

Lists conversations for a workspace. Each item includes the last message and unread count.

{
  "data": [
    {
      "id": "string",
      "type": "swarm | agent",
      "title": "string",
      "created_at": "ISO8601",
      "updated_at": "ISO8601",
      "unread_count": 0,
      "agent": {
        "id": "string",
        "name": "string",
        "role": "string",
        "slug": "string",
        "avatar": "string",
        "status": "string"
      },
      "last_message": "MessageData | null"
    }
  ]
}

agent is null for swarm conversations.

GET /v1/workspaces/{workspaceId}/conversations/{id}

Returns one conversation (same shape as a list item).

GET /v1/workspaces/{workspaceId}/conversations/{id}/messages

Lists messages with cursor-based pagination.

Query params: scrollId (string, cursor token), limit (int), direction ("forward" or "backward")

{
  "data": [
    {
      "id": "string",
      "conversation_id": "string",
      "role": "user | agent | system",
      "content": "MessageContent (see below)",
      "status": "pending | delivered | failed",
      "created_at": "ISO8601",
      "updated_at": "ISO8601",
      "local_id": "string | null",
      "agent": "AgentData | null",
      "attachments": [
        {
          "id": "string",
          "url": "string",
          "type": "image | video | audio | file",
          "name": "string",
          "size": 0,
          "mime_type": "string",
          "duration": "int | null"
        }
      ],
      "mentions": [
        {
          "agent_id": "string",
          "agent_name": "string",
          "offset": 0,
          "length": 0
        }
      ]
    }
  ],
  "pagination": {
    "next_scroll_id": "string",
    "prev_scroll_id": "string",
    "has_next": true,
    "has_prev": false
  }
}

MessageContent

content is a discriminated union on the type field:

type	Fields
text	text: string
action_card	title: string, description: string, actions: [{ id, label, style }], selected_action_id: string?
tool_status	tool: string, description: string, state: running | completed | failed
system	text: string
loading	(no additional fields)

ActionStyle values: primary, secondary, destructive.

POST /v1/workspaces/{workspaceId}/conversations/{id}/messages

Sends a new message to a conversation.

Request:

{
  "local_id": "string",
  "content": { "type": "text", "text": "Hello" },
  "attachments": [],
  "mentions": []
}

Response: returns the created MessageData object.

POST /v1/workspaces/{workspaceId}/messages/{id}/action

Responds to an action card by selecting one of its actions.

Request:

{ "action_id": "string" }

Response: returns the updated MessageData object.

Integrations

The integrations routes describe both built-in tools and OAuth-backed external apps.

GET /v1/integrations

Returns categories and a flat item list containing both tools and integrations.

{
  "data": {
    "categories": [
      {
        "id": "string",
        "name": "string",
        "image_url": "string"
      }
    ],
    "items": [
      {
        "name": "string",
        "description": "string",
        "icon_url": "string",
        "category_id": "string",
        "type": "tool | app",
        "provider": "google_calendar | gmail | slack | jira | notion | asana | github | zoom | null",
        "enabled": true
      }
    ]
  }
}

provider is null for built-in tools. category_id may be absent on integration-type items.

POST /v1/integrations/connect

Requests the OAuth configuration for a provider.

Request:

{ "provider": "gmail" }

Response:

{
  "client_id": "string",
  "redirect_url": "string",
  "authorization_endpoint": "string",
  "token_endpoint": "string",
  "scopes": ["string"],
  "additional_parameters": { "key": "value" }
}

POST /v1/integrations/callback

Sends the OAuth authorization code to the backend to complete the connection flow.

Request:

{
  "provider": "gmail",
  "authorization_code": "string",
  "code_verifier": "string",
  "redirect_url": "string"
}

Response: 204 No Content.

GET /v1/integrations/{provider}/accounts

Lists accounts the user has connected for a given provider.

{
  "data": [
    {
      "id": "string",
      "name": "string",
      "email": "string",
      "provider": "gmail"
    }
  ]
}

DELETE /v1/integrations/{provider}/accounts/{accountId}

Disconnects a specific provider account.

Response: 204 No Content.

PATCH /v1/tools/{name}

Toggles a built-in tool on or off for the current user.

Request:

{ "enabled": true }

Response: 204 No Content.

Notifications

GET /v1/notifications

Lists notifications with cursor-based pagination.

Query params: scrollId (string), limit (int)

{
  "data": [
    {
      "id": "string",
      "title": "string",
      "body": "string",
      "type": "agentMessage | systemAlert | workspaceUpdate",
      "created_at": "ISO8601",
      "is_read": false,
      "action_url": "string | null"
    }
  ],
  "pagination": {
    "next_scroll_id": "string",
    "prev_scroll_id": "string",
    "has_next": true,
    "has_prev": false
  }
}

POST /v1/notifications/{id}/read

Marks a single notification as read.

Response: 204 No Content.

POST /v1/notifications/read-all

Marks all notifications as read.

Response: 204 No Content.

GET /v1/notifications/preferences

Returns the user's notification preference flags.

{
  "data": {
    "push_enabled": true,
    "agent_messages": true,
    "system_alerts": true,
    "workspace_updates": true
  }
}

PATCH /v1/notifications/preferences

Updates notification preferences. All fields optional.

Request:

{
  "push_enabled": true,
  "agent_messages": true,
  "system_alerts": true,
  "workspace_updates": true
}

Response: 204 No Content.

Support

POST /v1/support/ticket

Submits a support ticket. Content-Type must be multipart/form-data.

Form parts:

Field	Type	Required
app_version	string	Yes
subject	string	Yes
description	string	Yes
attachments	file[]	No

Response: 204 No Content.

Realtime

The Socket.IO transport endpoint is /socket.io/, and the mobile client connects to namespace /v1.

Authentication uses the same security headers as HTTP (X-Token, X-Signature, X-Device-Info, X-Device-ID, X-Version, X-Timezone, X-Timestamp).

Client → Server Events

Event	Payload
workspace.subscribe	{ "workspace_ids": ["string"] }
workspace.unsubscribe	{ "workspace_ids": ["string"] }

Server → Client Events

Event	Payload
message.new	{ "message": MessageData }
message.updated	{ "message": MessageData }
agent.typing	{ "conversation_id": "string", "agent_id": "string", "is_typing": true }
agent.status	{ "agent_id": "string", "status": "AgentStatus" }
workspace.subscribed	{ "workspace_ids": ["string"] }

API Configuration Reference

Setting	Value
Base URL	Compile-time env constant
WebSocket	{baseUrl}/v1 via Socket.IO
Auth header	X-Token (Firebase ID token)
HMAC header	X-Signature = HMAC-SHA256({token}:{timestamp}, hmacSecret)
Extra headers	X-Device-Info, X-Device-ID, X-Version, X-Timezone, X-Timestamp
Connect timeout	10s
Send timeout	10s
Receive timeout	60s
JSON casing	snake_case

🔗 Terms On This Page

If a term below is unfamiliar, open its glossary entry. For the full list, go to Internal Glossary.

• Firebase JWT: The signed Firebase identity token used to authenticate a user request.
• FCM: Firebase Cloud Messaging, used for device push notifications.
• UserSwarm: The Crawbl custom resource that represents one user runtime and its lifecycle.
• Socket.IO: The realtime transport layer used to push events from the backend to connected clients.
• Cursor Pagination: A pagination style that returns opaque cursor tokens instead of page numbers.
• OAuth: The delegated login and consent flow used to connect external apps without storing user passwords.