recall

Retrieve ranked memory documents

Return one authoritative JSON result per selected document, with artifact context and document-local source evidence. Consumers own prompt, model, and display rendering.

post/api/v1/recall

Request

  • Base URL: https://api.past.dev
  • URL: https://api.past.dev/api/v1/recall
  • Auth: one of:
    • HTTP bearer
    • HTTP bearer

Request body

querystring required

Natural-language query.

limitinteger

Maximum number of documents in the page.

level'low' | 'medium' | 'high' | 'extra-high'

The evidence budget in words: low 8,000 tokens, medium 16,000, high 24,000, extra-high 32,000. A level above the plan's ceiling is lowered to it: 8,000 on Pay as you go and Flex, 32,000 on Enterprise. Send level or maxTokens, never both.

maxTokensinteger

An explicit evidence budget in tokens, for a caller who needs a figure the levels do not offer. Estimated from document content and excerpt text only, excluding JSON structure and metadata; lowered to the plan's ceiling in the same way; whole documents are kept or omitted.

queryTimestampstring date-time

The perspective of the read. Evidence at or before this instant is eligible. Defaults to now.

occurredFromstring date-time

Inclusive start of the occurrence window.

occurredTostring date-time

Inclusive end of the occurrence window. A start after the end returns 400 recall-range-invalid.

sort'relevance' | 'chronological'

chronological orders the selected documents oldest first and keeps each relevance rank.

identitystring required

Response

Ranked document results with source excerpts and the UTC recall perspective.

asOfstring date-time required
usedEvidenceTokensinteger required

Sum of per-document character-based estimates for content and excerpt text only; excludes JSON structure, IDs, dates and metadata. Not model-provider usage.

Changes

No recorded changes to this operation across all 1 revision of this API.