API Reference

getting started

Authentication

All API requests require a Bearer token in the Authorization header.

request headers
Authorization: Bearer your_token_here
Content-Type: application/json

All requests must include Content-Type: application/json. Responses use the same content type.

read_only

Read-Only Token

Access GET endpoints only. Perfect for AI tools that consume context.

full_access

Full Access Token

Access all endpoints — GET, POST, PATCH, DELETE. For management and automation.

Rate Limiting

API requests are limited to 100 requests per minute per token.

            429 response
            429 Too Many Requests
          
{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Please try again later.",
    "status": 429
  }
}

Error Handling

All errors follow a consistent JSON structure with a code, message, and HTTP status.

error format
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": { ... },    // optional, for validation errors
    "status": 4xx
  }
}

Status	Code	Description
`401`	`UNAUTHORIZED`	Invalid or missing access token
`403`	`FORBIDDEN`	Insufficient permissions or inactive workspace
`404`	`NOT_FOUND`	Resource not found
`422`	`VALIDATION_ERROR`	Invalid request data (includes `details`)
`429`	`RATE_LIMITED`	Rate limit exceeded

resource

Workspaces

List Workspaces

Returns all active workspaces for the current account.

GET/workspaces.json

Parameters

Name	Type	Description
page	integer	Page number (default: 1)

response200 OK
[
  {
    "id": 1,
    "name": "Project Alpha",
    "description": "Main project workspace",
    "memories_count": 42,
    "archived": false,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-04T14:22:00Z",
    "url": "https://recuerd0.ai/workspaces/1"
  }
]

Pagination headers X-Page, X-Per-Page, X-Total, X-Total-Pages, and Link are included in all list responses.

Get Workspace

Returns a single workspace with memory count and pinned status.

GET/workspaces/:id.json

response200 OK
{
  "id": 1,
  "name": "Project Alpha",
  "description": "Main project workspace",
  "memories_count": 42,
  "archived": false,
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-02-04T14:22:00Z",
  "url": "https://recuerd0.ai/workspaces/1"
}

Create Workspace

Creates a new workspace.

POST/workspaces.jsonfull_access

Parameters

Name	Type		Description
workspace[name]	string	required	Workspace name (max 100 characters)
workspace[description]	string		Workspace description

request
{
  "workspace": {
    "name": "New Project",
    "description": "A new workspace for the team"
  }
}

response201 Created
{
  "id": 2,
  "name": "New Project",
  "description": "A new workspace for the team",
  "memories_count": 0,
  "archived": false,
  "created_at": "2026-02-04T15:00:00Z",
  "updated_at": "2026-02-04T15:00:00Z",
  "url": "https://recuerd0.ai/workspaces/2"
}

Update Workspace

Updates an existing workspace.

PATCH/workspaces/:id.jsonfull_access

Parameters

Name	Type	Description
workspace[name]	string	Workspace name
workspace[description]	string	Workspace description

response200 OK
Returns the updated workspace object.

Archive Workspace

Archives a workspace. Archived workspaces become read-only.

POST/workspaces/:id/archive.jsonfull_access

response200 OK
Returns the workspace with "archived": true

Unarchive Workspace

Restores an archived workspace.

DELETE/workspaces/:id/archive.jsonfull_access

response200 OK
Returns the workspace with "archived": false

resource

Memories

List Memories

Returns all memories (latest versions only) for a workspace.

GET/workspaces/:workspace_id/memories.json

Parameters

Name	Type	Description
page	integer	Page number (default: 1)

response200 OK
[
  {
    "id": 1,
    "title": "Meeting Notes",
    "version": 1,
    "source": "manual",
    "tags": ["meetings", "q1"],
    "created_at": "2026-01-20T09:00:00Z",
    "updated_at": "2026-02-03T16:45:00Z",
    "url": "https://recuerd0.ai/workspaces/1/memories/1"
  }
]

Get Memory

Returns a memory with its content.

GET/workspaces/:workspace_id/memories/:id.json

response200 OK
{
  "id": 1,
  "title": "Meeting Notes",
  "version": 1,
  "source": "manual",
  "tags": ["meetings", "q1"],
  "created_at": "2026-01-20T09:00:00Z",
  "updated_at": "2026-02-03T16:45:00Z",
  "url": "https://recuerd0.ai/workspaces/1/memories/1",
  "content": {
    "body": "# Meeting Notes\n\nDiscussed Q1 goals..."
  },
  "workspace": {
    "id": 1,
    "name": "Project Alpha",
    "url": "https://recuerd0.ai/workspaces/1"
  }
}

Create Memory

Creates a new memory with content.

POST/workspaces/:workspace_id/memories.jsonfull_access

Parameters

Name	Type	Description
memory[title]	string	Memory title (max 255 characters)
memory[content]	string	Memory body (Markdown)
memory[source]	string	Source identifier
memory[tags]	array	Array of tag strings

request
{
  "memory": {
    "title": "API Documentation",
    "content": "# Overview\n\nThis document describes...",
    "tags": ["docs", "api"]
  }
}

response201 Created
Returns the created memory object with content.

Update Memory

Updates an existing memory.

PATCH/workspaces/:workspace_id/memories/:id.jsonfull_access

Parameters

Name	Type	Description
memory[title]	string	Memory title
memory[content]	string	Memory body
memory[source]	string	Source identifier
memory[tags]	array	Array of tags

response200 OK
Returns the updated memory object with content.

Delete Memory

Deletes a memory and all its versions.

DELETE/workspaces/:workspace_id/memories/:id.jsonfull_access

response204 No Content
Empty response body.

resource

Memory Versions

Create Version

Creates a new version of a memory. Fields default to the parent version values if not provided.

POST/workspaces/:workspace_id/memories/:memory_id/versions.jsonfull_access

Parameters

Name	Type	Description
version[title]	string	Version title (defaults to parent)
version[content]	string	Version body (defaults to parent)
version[source]	string	Source identifier (defaults to parent)
version[tags]	array	Tags (defaults to parent)

request
{
  "version": {
    "content": "# Updated Content\n\nRevised version..."
  }
}

response201 Created
{
  "id": 5,
  "title": "Meeting Notes",
  "version": 2,
  "source": "manual",
  "tags": ["meetings", "q1"],
  "created_at": "2026-02-04T16:00:00Z",
  "updated_at": "2026-02-04T16:00:00Z",
  "url": "https://recuerd0.ai/workspaces/1/memories/5",
  "content": {
    "body": "# Updated Content\n\nRevised version..."
  },
  "workspace": {
    "id": 1,
    "name": "Project Alpha",
    "url": "https://recuerd0.ai/workspaces/1"
  }
}

resource

Search

Search Memories

Full-text search across all memories in active workspaces. Supports FTS5 query operators.

GET/search.json?q=<query>

Parameters

Name	Type		Description
q	string	required	Search query (3–100 characters)
page	integer		Page number (default: 1)
workspace_id	integer		Filter results to a specific workspace

Query Operators (FTS5)

Operator	Example	Description
Term	`architecture`	Matches documents containing the substring
AND	`architecture AND design`	Both terms must appear
OR	`meeting OR standup`	Either term can appear
NOT	`design NOT draft`	First term must appear, second must not
Phrase	`"project timeline"`	Exact phrase match
Column	`title:architecture`	Search only in title field
Column	`body:implementation`	Search only in body field
Grouping	`(meeting OR standup) AND notes`	Parentheses for precedence

response200 OK
{
  "query": "architecture AND design",
  "total_results": 3,
  "results": [
    {
      "id": 1,
      "title": "Design Doc",
      "version": 1,
      "version_label": "v1",
      "has_versions": false,
      "tags": ["design"],
      "source": "manual",
      "snippet": "Initial architecture overview...",
      "created_at": "2026-01-20T09:00:00Z",
      "updated_at": "2026-02-03T16:45:00Z",
      "url": "https://recuerd0.ai/workspaces/1/memories/1",
      "workspace": {
        "id": 1,
        "name": "Project Notes",
        "url": "https://recuerd0.ai/workspaces/1"
      }
    }
  ]
}

Query must be 3–100 characters. Invalid FTS5 syntax returns a 422 with VALIDATION_ERROR.

Authentication

Read-Only Token

Full Access Token

Rate Limiting

Error Handling

Workspaces

List Workspaces

Get Workspace

Create Workspace

Update Workspace

Archive Workspace

Unarchive Workspace

Memories

List Memories

Get Memory

Create Memory

Update Memory

Delete Memory

Memory Versions

Create Version

Search

Search Memories

Product

Resources

Legal