API Reference

The Rekall REST API gives you full programmatic access to memories, entities, workflows, agents, and hives. All endpoints accept and return JSON.

Base URL

All API requests are made to the following base URL. All communication is encrypted over HTTPS. Plain HTTP requests will be rejected.

https://api.rekall.ai/v1

Versioning

The API version is included in the URL path. The current stable version is v1. When breaking changes are introduced, a new version will be released and the previous version will remain available for a deprecation period of at least 12 months.

Version header

You can also specify the API version via the X-Rekall-Version header. If both are provided, the URL path version takes precedence.

Content Types

The API exclusively uses JSON for request and response bodies. Set the Content-Type header to application/json for all requests that include a body.

curl -X POST https://api.rekall.ai/v1/memories \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer rk_your_api_key" \
  -d '{"type": "episodic", "content": "User completed onboarding"}'

Authentication

All API requests require authentication. Rekall uses Bearer tokens prefixed with rk_. Include your token in the Authorization header of every request.

Authorization: Bearer rk_your_api_key

For detailed authentication options including API key headers, query parameters, and OAuth 2.0, see the Authentication guide.

Response Format

All successful responses return a JSON object with a data field containing the requested resource or collection. List endpoints also include pagination metadata.

// Single resource
{
  "data": {
    "id": "mem_abc123",
    "type": "episodic",
    "content": "User completed onboarding",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

// Collection
{
  "data": [
    { "id": "mem_abc123", "type": "episodic", "content": "..." },
    { "id": "mem_def456", "type": "semantic", "content": "..." }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6Im1lbV9kZWY0NTYifQ==",
    "has_more": true,
    "total_count": 142
  }
}

Error responses use a different format with an error object. See Error Handling for details.

Pagination

List endpoints use cursor-based pagination by default. Pass the cursor parameter with the value from pagination.next_cursor to retrieve the next page. The default page size is 20 and can be adjusted with the page_size parameter (max 100).

For full pagination details, see the Pagination guide.