API & MCP

Recall provides two ways to integrate with your knowledge base:

• MCP Server — connect AI assistants like Claude, ChatGPT, Cursor, and others using the Model Context Protocol.
• Public API — access your cards and search your knowledge base from your own scripts, automations, or applications.

Both are managed from Settings → API & MCP in the Recall app.

MCP Server

The Recall MCP server lets AI assistants connect to your knowledge base using the Model Context Protocol. Once connected, an assistant can search, read, and write to your cards on your behalf.

Server URL: https://backend.getrecall.ai/mcp/

You can find this URL in Settings → API & MCP under the MCP Server section.

Quick Start

Claude

Click Open next to Claude in the MCP Server settings, or visit claude.ai/integrations/recall directly. Follow the prompts to authorize access.

ChatGPT

Click Open next to ChatGPT in the MCP Server settings, or visit chatgpt.com/g/recall-ai directly.

Other MCP Clients

Point any MCP-compatible client at the server URL above. The client will open a browser window where you sign in to Recall and approve the connection.

Authentication

The MCP server uses an OAuth-based flow. When an MCP client connects for the first time:

1. The client redirects you to a Recall authorization page.
2. You sign in (or confirm your identity if already signed in).
3. You review the requested permissions and click Allow access.
4. The client receives a token and can begin making requests.

No API key is needed — authentication is handled entirely through the browser.

Permissions

When connecting, the MCP client will request one or more of these scopes:

Tools

All four tools below require the kb:read scope.

search — Search Knowledge Base

Search your saved content by semantic + keyword matching.

Parameters

get_document_content — Get Document

Retrieve key content from a document as deduplicated chunks. Use after discovering a card via search or filter_by_metadata to read its complete content.

Parameters

filter_by_metadata — Filter Documents

Filter documents by metadata (date, tags, source URL). No semantic search. Returns previews with id, title, and created_at.

Parameters

explore_kb — Explore Knowledge Base

Explore knowledge base structure and statistics.

Parameters

Public API

The Public API lets you programmatically access your knowledge base over HTTP. You can list and filter your cards, retrieve their content, and run semantic searches.

Base URL: https://api.getrecall.ai/api/v1

Generate an API Key

Before you can make API calls, you need to create an API key:

1. Open the Recall web app and log in.
2. Navigate to Settings → API & MCP and find the API Keys section.
3. Click Create key, give it a name, and choose an expiration: Never, 1 year, 90 days, 30 days, or a Custom date.
4. Copy the generated key — it starts with sk_.

You can have up to 10 API keys at a time.

From the same settings page you can also view your active keys and delete any key you no longer need. Deleted keys stop working immediately.

Authentication

Every API request must include your key in the Authorization header:

Authorization: Bearer sk_a1b2c3d4e5f6g7h8i9j0k1l2

If your key is missing, invalid, or expired, you’ll receive a 401 Unauthorized response.

Endpoints

List Cards

GET /api/v1/cards

Returns cards matching your filters. When no filters are provided, all cards are returned.

Query Parameters

Response

{
  "results": [
    {
      "id": "card_abc123",
      "title": "My Card Title",
      "created_at": "Jan 15, 2025",
      "image": "https://example.com/image.png",
      "source_url": "https://example.com/article"
    }
  ],
  "total_count": 1
}

image and source_url are omitted when not available.

Get Card

GET /api/v1/cards/{card_id}

Returns a single card along with its content chunks.

Path Parameters

Query Parameters

Response

{
  "card_id": "card_abc123",
  "title": "My Card Title",
  "chunks": [
    {
      "chunk_id": "chunk_001",
      "content": "The actual text content of this chunk...",
      "source": "page 3",
      "timestamps": ["01:23", "04:56"]
    }
  ],
  "created_at": "Jan 15, 2025",
  "image": "https://example.com/image.png",
  "source_url": "https://example.com/article"
}

image, source_url, source, and timestamps are omitted when not available.

Search

GET /api/v1/search

Performs a semantic search across your cards and returns the most relevant content chunks.

Query Parameters

Response

{
  "documents": [
    {
      "card_id": "card_abc123",
      "title": "My Card Title",
      "created_at": "Jan 15, 2025",
      "image": "https://example.com/image.png",
      "source_url": "https://example.com/article",
      "chunks": [
        {
          "chunk_id": "chunk_001",
          "content": "Relevant text passage...",
          "source": "page 3",
          "timestamps": ["01:23"]
        }
      ]
    }
  ],
  "total_cards": 1,
  "total_chunks": 1
}

image, source_url, source, and timestamps are omitted when not available.

Validation Rules

Error Responses

All errors return a JSON body. Validation errors (422) include details about which parameter failed. Server errors (500) and not-found errors (404) include a request_id — share this with support if you need help troubleshooting.

401 Unauthorized

Returned when your API key is missing, invalid, or expired.

{
  "detail": {
    "message": "Invalid API key"
  }
}

422 Validation Error

Returned when a parameter doesn’t meet the validation rules.

{
  "detail": {
    "message": "date_from must be before or equal to date_to"
  }
}

404 Not Found

Returned when the requested resource doesn’t exist.

{
  "detail": {
    "message": "The requested resource was not found.",
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

500 Internal Server Error

Returned when something unexpected goes wrong on our end.

{
  "detail": {
    "message": "An internal error occurred. Contact support with this request ID.",
    "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}