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.

Graph endpoints

The graph endpoints read the patient context graph directly. Audit the Patient Graph walks this graph end to end. The endpoints are all Technical preview.

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.

API stability

The /v{n} prefix does not indicate stability. Every endpoint declares a tier, published as x-state on its operation in the OpenAPI spec:

• Generally available — breaks only at a new version prefix.
• Technical preview — promises nothing. It may change or disappear in any release, including a patch.
• Deprecated — still works, unchanged, and will be removed in a future release.

Anything other than generally available sends a runtime warning header:

Warning: 299 ContextEngine-1.4.0 "Deprecated: this endpoint will be removed in a future release."

MCP server stability is never guaranteed; its tools are optimized for agents and change with the product.

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.