REST API Reference

Complete reference for all public endpoints. Base URL: https://api.telepathine.ai

Sessions

POST /v1/sessions Auth

Create a new memory session for a project. Sessions track the lifecycle of an agent's work.

Parameters

Name	In	Type	Required	Description
project	body	string	Required	Project identifier/slug
contentSessionId	body	string	Optional	Custom session ID (auto-generated if omitted)
userPrompt	body	string	Optional	Initial user prompt for the session
workspaceContext	body	string	Optional	Git, host, and agent context

Response example

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contentSessionId": "cs_1716300000_a1b2c3d4",
  "project": "my-project",
  "status": "active",
  "workspaceContext": { "git": { "branch": "main" } }
}

GET /v1/sessions Auth

List or search sessions. Filter by project or content session ID.

Parameters

Name	In	Type	Required	Description
project	query	string	Optional	Filter by project slug
content_session_id	query	string	Optional	Find session by content session ID
limit	query	number	Optional	Max results (default 5, max 50)

Response example

{
  "items": [{ "id": "...", "project": "my-project", "status": "active" }]
}

POST /v1/sessions/:id/summarize Auth

Trigger LLM-powered summarization for a session. Generates structured summary with findings.

Parameters

Name	In	Type	Required	Description
id	path	string	Required	Session ID

Response example

{
  "summaryId": 100,
  "status": "completed"
}

POST /v1/sessions/:id/complete Auth

Mark a session as completed. Optionally triggers async summarization.

Parameters

Name	In	Type	Required	Description
id	path	string	Required	Session ID
summarize	query	boolean	Optional	Set to "true" to auto-summarize on completion

Response example

{
  "id": "550e8400-...",
  "status": "completed"
}

Observations

POST /v1/sessions/:id/observations Auth

Record a structured observation within a session. Observations are the core memory unit.

Parameters

Name	In	Type	Required	Description
id	path	string	Required	Session ID
type	body	string	Required	Observation type (decision, change, learning, etc.)
text	body	string	Optional	Raw observation text
title	body	string	Optional	Short title
narrative	body	string	Optional	Narrative description
facts	body	string	Optional	Key facts extracted
concepts	body	string	Optional	Key concepts identified
filesTouched	body	string	Optional	Files modified during this observation

Response example

{
  "id": "42",
  "type": "decision",
  "createdAt": "2026-05-21T10:30:00Z"
}

POST /v1/sessions/:id/observations/raw Auth

Record a raw tool-use observation for agent-powered processing. Queued for async LLM enrichment.

Parameters

Name	In	Type	Required	Description
id	path	string	Required	Session ID
tool_name	body	string	Required	Name of the tool used
tool_input	body	string	Required	Tool input parameters
tool_response	body	string	Required	Tool output/response

Response example

{
  "status": "queued",
  "sessionId": "550e8400-..."
}

POST /v1/sessions/:id/observations/batch Auth

Batch record up to 50 observations in a single request.

Parameters

Name	In	Type	Required	Description
id	path	string	Required	Session ID
observations	body	string	Required	Array of 1-50 observation objects

Response example

{
  "created": 5,
  "ids": ["42", "43", "44", "45", "46"]
}

GET /v1/observations Auth

List observations with optional filters by project, type, or session.

Parameters

Name	In	Type	Required	Description
project	query	string	Optional	Filter by project slug
type	query	string	Optional	Filter by observation type
memorySessionId	query	string	Optional	Filter by session ID
limit	query	number	Optional	Max results (default 50, max 500)
offset	query	number	Optional	Pagination offset

Response example

{
  "items": [{ "id": "42", "type": "decision", "title": "Use PostgreSQL" }],
  "count": 1,
  "scope": { "projects": ["my-project"], "type": "explicit" }
}

Search

GET /v1/search Auth

Hybrid search combining full-text search (FTS) and semantic vector similarity. Returns ranked results.

Parameters

Name	In	Type	Required	Description
q	query	string	Required	Search query text
project	query	string	Optional	Scope to project slug
limit	query	number	Optional	Max results (default 20, max 100)
mode	query	string	Optional	Search mode: "hybrid" (default), "fts", or "vector"
type	query	string	Optional	Filter by observation type
from	query	string	Optional	Start date (ISO 8601)
to	query	string	Optional	End date (ISO 8601)

Response example

{
  "hits": [{ "id": "42", "score": 0.87, "source": "hybrid", "title": "Auth decision" }],
  "count": 1,
  "mode": "hybrid",
  "scope": { "projects": ["my-project"], "type": "explicit" }
}

GET /v1/timeline Auth

Get a chronological feed of observations, filtered by project and time range.

Parameters

Name	In	Type	Required	Description
project	query	string	Optional	Filter by project slug
before	query	string	Optional	Return observations before this date
after	query	string	Optional	Return observations after this date
limit	query	number	Optional	Max results (default 50)

Response example

{
  "items": [{ "id": "42", "type": "decision", "title": "Use PostgreSQL", "created_at": "..." }],
  "count": 1
}

GET /v1/decisions Auth

List all decision-type observations for a project. Decisions capture architectural and design choices.

Parameters

Name	In	Type	Required	Description
project	query	string	Optional	Filter by project slug
limit	query	number	Optional	Max results (default 20)

Response example

{
  "items": [{ "id": "42", "type": "decision", "title": "Auth approach", "narrative": "..." }],
  "count": 1
}

GET /v1/changes Auth

List all change-type observations for a project. Changes track file modifications and code updates.

Parameters

Name	In	Type	Required	Description
project	query	string	Optional	Filter by project slug
limit	query	number	Optional	Max results (default 20)

Response example

{
  "items": [{ "id": "42", "type": "change", "title": "Refactor auth", "files_touched": "src/auth.ts" }],
  "count": 1
}

Context

GET /v1/context Auth

Get candidate observations for context injection. Returns ranked, relevant observations for a project.

Parameters

Name	In	Type	Required	Description
project	query	string	Required	Project slug
q	query	string	Optional	Optional search query for relevance filtering
limit	query	number	Optional	Max results (default 20, max 50)

Response example

{
  "items": [{ "id": "42", "type": "retrospective", "title": "Session summary" }],
  "count": 1
}

GET /v1/context/inject Auth

Get formatted, compressed context for agent injection. Uses progressive disclosure: header, timeline, summary, footer.

Parameters

Name	In	Type	Required	Description
projects	query	string	Optional	Comma-separated project slugs
limit	query	number	Optional	Max observations (default 15)
format	query	string	Optional	Output format: "text" (default) or "json"

Response example

{
  "context": "# [my-project] recent context\n\n## Timeline\n...",
  "format": "text",
  "observationCount": 12
}

Projects

GET /v1/projects Auth

List all projects for the authenticated tenant.

Response example

{
  "items": [{ "id": "...", "slug": "my-project" }]
}

POST /v1/projects/config Auth

Create or update project configuration including visibility, sharing, and inheritance rules.

Parameters

Name	In	Type	Required	Description
project	body	string	Required	Project slug
visibility	body	string	Optional	Visibility: "private", "tenant", or "shared"
sharedWith	body	string	Optional	Array of tenant IDs to share with
inheritFrom	body	string	Optional	Array of project slugs to inherit context from

Response example

{
  "id": "...",
  "project": "my-project",
  "visibility": "tenant"
}

GET /v1/projects/config Auth

List all project configurations for the authenticated tenant.

Response example

{
  "items": [{ "project": "my-project", "visibility": "private" }],
  "count": 1
}

GET /v1/workspaces Auth

List workspace contexts (git branch, host, agent) from sessions. Track active and stale workspaces.

Parameters

Name	In	Type	Required	Description
project	query	string	Optional	Filter by project slug
branch	query	string	Optional	Filter by git branch
hostname	query	string	Optional	Filter by hostname
limit	query	number	Optional	Max results (default 20, max 100)

Response example

{
  "workspaces": [{ "project": "my-project", "git": { "branch": "main" }, "status": "active" }],
  "count": 1
}

Events

GET /v1/events Auth

Server-Sent Events (SSE) stream for real-time observation and session events.

Response example

event: connected
data: {"status":"ok","tenantId":"..."}

event: thought
data: {"action":"created","observation":{"id":"42","type":"decision"}}

System

GET /v1/health

Health check endpoint. Returns service status, database connectivity, and embedding provider status.

Response example

{
  "status": "ok",
  "db": true,
  "redis": true,
  "embedding": { "provider": "openai", "configured": true, "reachable": true }
}

SDK Examples

TypeScript SDK

TypeScript

import { AgentMemoryClient } from '@ai-memory/sdk';

const mem = new AgentMemoryClient({
  apiKey: process.env.TELEPATHINE_API_KEY!,
  workerUrl: 'https://api.telepathine.ai',
});

const session = await mem.createSession({ project: 'my-project' });
await mem.appendObservation(session.id, {
  type: 'decision', text: 'Use PostgreSQL', title: 'Database choice',
});
const results = await mem.search({ q: 'database', mode: 'hybrid' });
const ctx = await mem.getContext('my-project');

Python SDK

Python

from agent_memory import AgentMemoryClient

mem = AgentMemoryClient(
    api_key=os.environ["TELEPATHINE_API_KEY"],
    worker_url="https://api.telepathine.ai",
)

session = mem.create_session(project="my-project")
mem.append_observation(
    session_id=session["id"],
    observation={"type": "decision", "text": "Use PostgreSQL", "title": "Database choice"},
)
results = mem.search(q="database", mode="hybrid")
ctx = mem.get_context("my-project")