v9 (current) v8
Edit Page

Sophia AI - API Documentation

Cloud

Overview

The Sophia API provides RESTful endpoints for managing the AI service, including chat operations, document management, context configuration, API tokens, and system administration.

Authentication

The web interface uses cookie-based authentication. Login to obtain an HttpOnly session cookie:

curl -X POST "https://sophia-api.restheart.com/token/cookie" \
  -H "Authorization: Basic <base64-credentials>"

The response sets an rh_auth HttpOnly cookie and returns a JWT in the body (used to decode roles client-side).

Bearer Token Authentication (API & MCP)

For programmatic access and MCP clients, use a JWT bearer token:

Authorization: Bearer <jwt-token>

API tokens are issued through the admin panel or the token API (see [_api_tokens]).

Chat Operations

Create Chat Message

Creates a new chat message with a prompt.

Endpoint: POST /chats

Parameters:

  • wm=upsert — write mode parameter

  • chatId — unique identifier for the chat session

  • prompt — user prompt

Request:

curl -X POST "https://sophia-api.restheart.com/chats?wm=upsert" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "chat-123",
    "prompt": "What is RESTHeart?"
  }'

Response:

{
  "_id": {"$oid": "6507f1f462f8b7c123456789"},
  "chatId": "chat-123",
  "prompt": "What is RESTHeart?",
  "status": "waiting",
  "_etag": {"$oid": "6507f1f462f8b7c123456789"}
}

Subscribe to Chat Updates

Subscribe to real-time chat updates using WebSocket connection.

Endpoint: WS /chats/_streams/subscribe

Parameters:

  • avars={"chatId":"<chat-id>"} — chat session to subscribe to

WebSocket Connection:

websocat "wss://sophia-api.restheart.com/chats/_streams/subscribe?avars={\"chatId\":\"chat-123\"}" \
  --header "Authorization: Bearer <jwt-token>"

Response Stream (standard mode):

{
  "fullDocument": {
    "_id": {"$oid": "6507f1f462f8b7c123456789"}
  },
  "updateDescription": {
    "updatedFields": {
      "chunks.0": "RESTHeart is a ",
      "status": "streaming"
    }
  }
}

Agentic Mode Events

When a context has agenticMode enabled and streamThinkingEvents is true, the WebSocket stream includes agent events before the text response:

Tool start event:

{
  "updateDescription": {
    "updatedFields": {
      "events.0": {
        "type": "tool_start",
        "iteration": 1,
        "toolUseId": "toolu_01ABC",
        "tool": "search",
        "args": {"query": "RESTHeart configuration"}
      }
    }
  }
}

Tool result event:

{
  "updateDescription": {
    "updatedFields": {
      "events.1": {
        "type": "tool_result",
        "iteration": 1,
        "toolUseId": "toolu_01ABC",
        "tool": "search",
        "resultSummary": "Found 5 relevant segments",
        "durationMs": 342
      }
    }
  }
}

Text start event (agentic phase ends):

{
  "updateDescription": {
    "updatedFields": {
      "events.2": {
        "type": "text_start"
      },
      "chunks.0": "Based on my research, RESTHeart is..."
    }
  }
}

Context Management

Contexts define the behaviour of Sophia for a specific knowledge domain. They replace the legacy promptTemplates endpoint.

List Contexts

Endpoint: GET /contexts

Request:

curl "https://sophia-api.restheart.com/contexts" \
  -H "Authorization: Bearer <jwt-token>"

Get Context

Endpoint: GET /contexts/{contextId}

Request:

curl "https://sophia-api.restheart.com/contexts/restheart" \
  -H "Authorization: Bearer <jwt-token>"

Response:

{
  "_id": "restheart",
  "template": "You are Sophia, AI assistant for RESTHeart...\n\n<documents-placeholder>\n\n<history-placeholder>\n\n<userprompt>",
  "welcome": "Hello! I'm Sophia, your RESTHeart assistant.",
  "options": {
    "max_tokens_to_sample": 4000,
    "temperature": 0.3,
    "top_k": 250,
    "top_p": 1.0,
    "relevantsNumCandidates": 5000,
    "relevantsLimit": 5,
    "historyLimit": 3,
    "userPromptMaxChars": 500,
    "agenticMode": true,
    "maxAgentIterations": 5,
    "streamThinkingEvents": true,
    "extendedThinking": false,
    "modelId": null
  },
  "tags": ["restheart"],
  "mcp": {
    "description": "Sophia knowledge base for RESTHeart — search the official docs, plugin API, configuration guides, and source code."
  }
}

Create or Replace Context

Endpoint: PUT /contexts/{contextId}

Request:

curl -X PUT "https://sophia-api.restheart.com/contexts/restheart" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "template": "You are Sophia...\n\n<documents-placeholder>\n\n<history-placeholder>\n\n<userprompt>",
    "tags": ["restheart"],
    "options": {
      "temperature": 0.3,
      "relevantsLimit": 5,
      "agenticMode": true,
      "maxAgentIterations": 10
    },
    "mcp": { "description": "RESTHeart knowledge base." }
  }'

Update Context (Partial)

Endpoint: PATCH /contexts/{contextId}

Request:

curl -X PATCH "https://sophia-api.restheart.com/contexts/restheart" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"options": {"relevantsLimit": 8, "temperature": 0.2}}'

Delete Context

Endpoint: DELETE /contexts/{contextId}

curl -X DELETE "https://sophia-api.restheart.com/contexts/restheart" \
  -H "Authorization: Bearer <jwt-token>"

Document Management

Upload Document

Endpoint: POST /docs.files

Parameters:

  • wm=upsert — write mode

  • metadata — JSON metadata including filename and tags

Request:

curl -X POST "https://sophia-api.restheart.com/docs.files?wm=upsert" \
  -H "Authorization: Bearer <jwt-token>" \
  -F "file=@document.pdf" \
  -F 'metadata={"filename": "document.pdf", "tags": ["public", "documentation"]}'

List Documents

Endpoint: GET /docs.files

Parameters:

  • page=<number> — pagination

  • pagesize=<number> — items per page (default: 100)

  • filter=<mongodb-filter> — MongoDB filter query

Request:

curl "https://sophia-api.restheart.com/docs.files?page=1&pagesize=20" \
  -H "Authorization: Bearer <jwt-token>"

Delete Document

Endpoint: DELETE /docs.files/{documentId}

curl -X DELETE "https://sophia-api.restheart.com/docs.files/6507f1f462f8b7c123456789" \
  -H "Authorization: Bearer <jwt-token>"

Deleting a document also removes all associated text segments.

Text Segments and Vector Search

Search Text Segments

Perform semantic search across processed document segments.

Endpoint: GET /textSegments/_aggrs/search

Parameters:

  • prompt=<query> — search query for semantic matching

  • avars=<variables> — additional variables (tags, context)

Request:

curl "https://sophia-api.restheart.com/textSegments/_aggrs/search?prompt=MongoDB%20queries" \
  -H "Authorization: Bearer <jwt-token>"

With context tag filter:

curl "https://sophia-api.restheart.com/textSegments/_aggrs/search?prompt=MongoDB%20queries&avars={\"tags\":[\"public\"]}" \
  -H "Authorization: Bearer <jwt-token>"

Response:

[
  {
    "_id": {"$oid": "6507f1f462f8b7c123456789"},
    "text": "MongoDB queries can be performed using various operators...",
    "metadata": {
      "filename": "mongodb-guide.pdf",
      "tags": ["public", "database"],
      "path": "guides/database"
    },
    "score": 0.8945
  }
]

List Text Segments

Endpoint: GET /textSegments

curl "https://sophia-api.restheart.com/textSegments?pagesize=10" \
  -H "Authorization: Bearer <jwt-token>"

API Tokens

Issue a Token

Endpoint: POST /tokens

Request:

curl -X POST "https://sophia-api.restheart.com/tokens" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "mcp-client",
    "context": "restheart",
    "tags": ["restheart"]
  }'

Response:

{
  "_id": "jti-abc123",
  "username": "mcp-client",
  "context": "restheart",
  "tags": ["restheart"],
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "createdAt": "2025-01-15T10:30:00Z"
}
Note
 The token field is returned only once at creation time.

List Tokens

Endpoint: GET /tokens

Returns token metadata without JWT values.

curl "https://sophia-api.restheart.com/tokens" \
  -H "Authorization: Bearer <jwt-token>"

Revoke a Token

Endpoint: PATCH /tokens/{jti}

curl -X PATCH "https://sophia-api.restheart.com/tokens/jti-abc123" \
  -H "Authorization: Bearer <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{"revoked": true}'

Delete a Token

Endpoint: DELETE /tokens/{jti}

curl -X DELETE "https://sophia-api.restheart.com/tokens/jti-abc123" \
  -H "Authorization: Bearer <jwt-token>"

Error Handling

HTTP Status Codes

  • 200 OK — request successful

  • 201 Created — resource created

  • 204 No Content — request successful, no content returned

  • 400 Bad Request — invalid request parameters

  • 401 Unauthorized — authentication required

  • 403 Forbidden — access denied

  • 404 Not Found — resource not found

  • 409 Conflict — resource conflict

  • 429 Too Many Requests — rate limit exceeded

  • 500 Internal Server Error — server error

Error Response Format

{
  "http_status_code": 400,
  "http_status_description": "Bad Request",
  "message": "Invalid request parameters",
  "exception": "ValidationException",
  "exception_message": "Missing required field: chatId"
}