API

The Recall API lets you access your knowledge base over HTTP. Use it to list and filter your cards, retrieve their content, and run semantic searches from your own scripts, automations, or applications.

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

Getting Started

1. Generate an API key

1. Open the Recall web app and log in.
2. Go 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. Active keys are listed on the same settings page, and any key you delete stops working immediately.

2. Authenticate requests

Every request must include your key in the Authorization header:

Authorization: Bearer sk_a1b2c3d4e5f6g7h8i9j0k1l2

If your key is missing, invalid, or expired, the API returns 401 Unauthorized.

3. Make your first request

curl "https://backend.getrecall.ai/api/v1/cards" \
  -H "Authorization: Bearer sk_a1b2c3d4e5f6g7h8i9j0k1l2"

Endpoints

List cards

GET /api/v1/cards

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

Query parameters

Example

curl "https://backend.getrecall.ai/api/v1/cards?source_url_contains=example.com" \
  -H "Authorization: Bearer sk_..."

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 a card

GET /api/v1/cards/{card_id}

Returns a single card along with its content chunks.

Path parameters

Query parameters

Example

curl "https://backend.getrecall.ai/api/v1/cards/card_abc123?focus_query=pricing&max_chunks=10" \
  -H "Authorization: Bearer sk_..."

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

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

Query parameters

Example

curl "https://backend.getrecall.ai/api/v1/search?q=spaced+repetition&mode=focused" \
  -H "Authorization: Bearer sk_..."

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"
  }
}

Looking for MCP?

If you’re connecting an AI assistant (Cursor, Claude Desktop, etc.) rather than writing your own code, see the MCP Server docs.