Recall API

Semantic search with scope-filtered results.

Recall Memories

POST /api/recall

Performs semantic search across memories the caller is cleared for. Every result includes a citation.

Request Body

Field	Type	Required	Description
`query`	string	Yes	What you want to know
`k`	number	No	Number of results (1-20, default 8)

Headers

Authorization: Bearer crtx_YOUR_KEY_HERE
Content-Type: application/json

Response (Allowed)

{
  "allowed": true,
  "results": [
    {
      "memory_id": "uuid",
      "title": "API Rate Limiting Policy",
      "content": "All external API endpoints must implement rate limiting...",
      "scope": "engineering",
      "score": 0.89,
      "citation": {
        "source": "GitHub",
        "source_url": "https://github.com/org/repo/pull/123",
        "author": "John Doe",
        "timestamp": "2025-01-15T10:30:00Z"
      }
    }
  ],
  "allowed_scopes": ["engineering", "public-docs"],
  "audit_id": "uuid"
}

Response (Denied)

{
  "allowed": false,
  "results": [],
  "reason": "No memories cleared for your role within scopes [engineering]. Content may exist in scopes you are not cleared for.",
  "allowed_scopes": ["public-docs"],
  "audit_id": "uuid"
}

Denials are a feature. Recall never silently returns nothing — it returns an explicit denial object and logs it to the audit trail.

Error Responses

Status	Description
`401`	Invalid or missing agent key
`400`	Empty query