API Reference

Quick Start

Get running in under 5 minutes. Create an account, grab your API key from the dashboard, and make your first request.

curl -X POST https://api.ricord.ai/v1/ingest/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "I prefer TypeScript over Python" },
      { "role": "assistant", "content": "Noted. TypeScript it is." }
    ],
    "session_id": "session_001"
  }'

curl -X POST https://api.ricord.ai/v1/memories/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "What language does the user prefer?" }'

curl https://api.ricord.ai/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

MCP Setup

Install the Ricord MCP server to give Claude Code, Cursor, Windsurf, VS Code, claude.ai — and any MCP-compatible client — persistent memory across all sessions.

npx ricord@latest install

URL:  https://mcp.ricord.ai/mcp
Auth: OAuth (click Connect — opens ricord.ai login)

# claude.ai → Settings → Integrations → Add custom integration
# ChatGPT  → Settings → Connectors → Add custom connector
#            (requires ChatGPT Pro / Team / Enterprise)

{
  "mcpServers": {
    "ricord": {
      "command": "npx",
      "args": ["-y", "--package=ricord", "ricord-mcp"],
      "env": { "RICORD_API_KEY": "YOUR_API_KEY" }
    }
  }
}

API Playground

Test the hybrid search endpoint directly from your browser. Paste your API key and try a query.

Authentication

All requests require an Authorization header. Two auth methods are supported:

Authorization: Bearer rc_live_abc123...

Authorization: Bearer eyJhbGciOiJS...

Rate limit headers on every response: X-RateLimit-Remaining, X-RateLimit-Reset. On 429, check Retry-After.

Ingest

Three ways to get data in. Use conversations for full session pipelines (turns → facts → KB → graph). Use source to ingest URLs, PDFs, YouTube videos, and other rich media. Use insert for raw turn ingestion with async queue support.

Hybrid Search

Cross-layer search across turns, facts, KB pages, and the knowledge graph. Returns a single LLM-ready context string.

Knowledge Wiki

Structured, versioned knowledge articles with semantic search. Supports types, maturity levels, conflict detection, and automatic deprecation. Accessible at /v1/memories.

Knowledge Graph

Entity and relationship graph built automatically from ingested content. Traverse entities, explore neighborhoods, and get snapshots for graph visualization.

KB Pages

Automatically synthesized canonical wiki pages built from ingested conversations. Each page is a living document that rolls up facts, references, and cross-links. Browse, edit, refresh, and export your KB.

KB Intelligence

Higher-order reasoning over your knowledge base. Challenge claims, surface patterns, bridge topics, and find contradictions.

Memories

Manually save, update, and delete individual facts, preferences, and decisions. Use these when you want precise control — the ingest endpoints will also extract memories automatically from conversations.

Preferences

Aggregated user preferences built automatically from ingested conversations. Override explicit values to lock-in choices over auto-inferred ones.

Embeddings

OpenAI-compatible embeddings endpoint. Supports OpenAI and Google models with automatic provider routing.

Assets

Upload and manage files. Two lifecycle zones: permanent (persists indefinitely) and staging (auto-expires).

Usage & Credits

Monitor your credit balance, usage patterns, and rate limits. 1 credit = $0.01 USD. All usage endpoints are free.

API Keys

Create and manage API keys programmatically. These endpoints require Firebase ID token authentication (not API key). Max 25 keys per account.

Data Export & Import

Export all your data at any time and restore it via import. Covers wiki articles, memories, and knowledge base pages with full relationship data. No credit charge. GDPR-compliant. Export format: ricord-export-v1.

MCP Tools Reference

The 13 MCP tools your agent gets after install — 8 core memory + 5 wiki — covering save, recall, correction, procedures, account, and the auto-organized wiki.

Health

Service health endpoints. No authentication required.

Error Handling

All errors return a consistent JSON object with a machine-readable type and human-readable message.

{
  "error": {
    "type": "insufficient_credits_error",
    "message": "Insufficient credits. Balance: 2, required: 10",
    "param": null,
    "code": "insufficient_credits"
  }
}

async function withRetry(fn, maxAttempts = 3) {
  for (let i = 0; i < maxAttempts; i++) {
    try {
      return await fn();
    } catch (err) {
      if (i === maxAttempts - 1) throw err;
      // Use Retry-After header for 429, exponential backoff for 5xx
      const delay = Math.pow(2, i) * 1000 + Math.random() * 500;
      await new Promise(r => setTimeout(r, delay));
    }
  }
}