API Overview

The Clinia Context Engine exposes two API surfaces backed by the same underlying data.

Base URL

https://<workspace-id>.w.clinia.cloud

Replace <workspace-id> with your workspace identifier.

REST API

Use REST for server-side integrations, dashboards, or when you need ingest endpoints.

See Sessions for the session/memory lifecycle behind the sessions endpoints. Session handling is controlled by the implementer through these REST endpoints.

OAuth scopes

Every endpoint declares a required scope. The scope is enforced on every request — a token that does not carry the required scope is rejected with HTTP 403 and a WWW-Authenticate: Bearer error="insufficient_scope" response header.

A credential's scope is set at creation time via its Access level (Read or Read & Write). See Manage Credentials for how to create a credential with the right access level.

MCP Tools

The MCP endpoint at /mcp is designed for AI agent integration. It exposes the Virtual File System as four tools:

Use MCP when building AI agents with the Model Context Protocol SDK. The server uses HTTP transport with SSE for streaming.

MCP tools require a read scope token. Pass it as Authorization: Bearer <token> in the request headers.

MCP Client Setup

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

const transport = new SSEClientTransport(new URL("https://<workspace-id>.w.clinia.cloud/mcp"));
const client = new Client({ name: "my-agent", version: "1.0.0" });
await client.connect(transport);

The MCP transport is stateless: there is no client-level session to track, and no relation to the patient-scoped Sessions resource used for tracking a conversation and generating memories.