past-dev Recall API

openapi: 3.2.0
info:
  title: Past Dev Recall API
  version: 1.0.0
  contact:
    name: past.dev
    url: https://past.dev/call
    email: support@past.dev
  description: 'Operations tagged recall across 2 of this provider''s published API definitions: past-dev-openapi.json, past-dev.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.past.dev
  description: Production
security:
- bearerAuth: []
tags:
- name: recall
  description: Retrieve ranked memory documents.
paths:
  /api/v1/recall:
    post:
      operationId: recall
      tags:
      - recall
      security:
      - bearerAuth: []
      - agentTokenAuth:
        - memory:read
      summary: Retrieve ranked memory documents
      description: Return one authoritative JSON result per selected document, with artifact context and document-local source evidence. Consumers own prompt, model, and display rendering.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecallRequest'
      responses:
        '200':
          description: Ranked document results with source excerpts and the UTC recall perspective.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecallResponse'
        '400':
          description: The request is malformed or violates a field constraint. Match behavior on the response code field.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 'missing-api-key: no bearer. malformed-api-key: the header or the key has the wrong shape, or an agent token was sent to a route that accepts keys only. unauthorized: the key is unknown, expired, revoked, or of the kind this route refuses, or the agent token is invalid or expired.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '402':
          description: 'out-of-credits: the recall costs 1 credit and the balance cannot pay for it. Every recall costs 1 credit on Pay as you go; on Flex and Enterprise a recall costs nothing within fair use and 1 credit above it, and only above it is it refused for credits. `data` carries `creditsLeft`, `creditsNeeded` and `resetsOn`. Do not retry: buy credits, or wait for `resetsOn`.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 'project-archived: the project of the key, or the project an agent token names, is archived. Unarchive it in the console to resume. insufficient-scope: the agent token does not carry the scope of the route.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: The plan's requests per minute are exceeded, which carries no body, or `spend-cap-reached` where the recall is priced and the billing period's spend cap is reached. No plan caps the number of recall calls.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure uses the same JSON error envelope.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.past.dev
      description: Production
components:
  schemas:
    RecallSource:
      type: object
      description: Evidence for this document grouped by canonical source id and date; not the artifact's complete provenance. Original source documents have no duplicated body in excerpts.
      required:
      - sourceId
      - occurredAt
      - excerpts
      additionalProperties: false
      properties:
        sourceId:
          type: string
        occurredAt:
          type: string
          format: date-time
        metadata:
          description: Caller metadata, exactly as sent; omitted when none was sent. Untrusted descriptive context.
        label:
          type: string
          description: The caller's label for the source, as sent at ingest; omitted when none was sent.
        excerpts:
          type: array
          items:
            type: string
          description: Verbatim supporting quotations. Repeated quotations are preserved.
    RecallRequest:
      type: object
      required:
      - query
      - identity
      additionalProperties: false
      properties:
        query:
          type: string
          description: Natural-language query.
        limit:
          type: integer
          minimum: 1
          maximum: 200
          default: 100
          description: Maximum number of documents in the page.
        level:
          type: string
          enum:
          - low
          - medium
          - high
          - extra-high
          default: low
          description: '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.'
        maxTokens:
          type: integer
          minimum: 1
          description: 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.
        queryTimestamp:
          type: string
          format: date-time
          description: The perspective of the read. Evidence at or before this instant is eligible. Defaults to now.
        occurredFrom:
          type: string
          format: date-time
          description: Inclusive start of the occurrence window.
        occurredTo:
          type: string
          format: date-time
          description: Inclusive end of the occurrence window. A start after the end returns 400 recall-range-invalid.
        sort:
          type: string
          enum:
          - relevance
          - chronological
          default: relevance
          description: chronological orders the selected documents oldest first and keeps each relevance rank.
        identity:
          type: string
          maxLength: 200
    RecallArtifact:
      type: object
      required:
      - id
      - kind
      - occurredAt
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        kind:
          type: string
          description: 'source is an original data point. Any other value is the kind of a derived memory: observation, claim, rule, membership, identity, mention or temporal-anchor. The list can grow; treat an unknown value as a memory. The Concepts page of the docs defines each kind.'
        occurredAt:
          type: string
          format: date-time
        supersededAt:
          type: string
          format: date-time
          description: Present when a later statement readable by this viewer superseded the artifact.
    RecallResponse:
      type: object
      required:
      - asOf
      - usedEvidenceTokens
      - results
      additionalProperties: false
      properties:
        asOf:
          type: string
          format: date-time
        usedEvidenceTokens:
          type: integer
          description: Sum of per-document character-based estimates for content and excerpt text only; excludes JSON structure, IDs, dates and metadata. Not model-provider usage.
        results:
          type: array
          items:
            $ref: '#/components/schemas/RecallResult'
        pending:
          $ref: '#/components/schemas/RecallPending'
    Error:
      type: object
      required:
      - code
      - status
      properties:
        code:
          type: string
          description: Stable kebab-case identifier.
        status:
          type: integer
          description: HTTP status repeated in the body.
        debugMessage:
          type: string
        data: {}
    RecallPending:
      type: object
      description: Present only while ingestions of the project are still processing. Their memory is not in this recall yet.
      required:
      - ingestions
      - dataPoints
      - since
      - message
      additionalProperties: false
      properties:
        ingestions:
          type: integer
          minimum: 1
          description: Ingestions accepted and not yet complete or failed.
        dataPoints:
          type: integer
          minimum: 0
          description: The data points those ingestions carry.
        since:
          type: string
          format: date-time
          description: When the oldest of them was accepted.
        message:
          type: string
          description: One sentence for a person or an agent. The wording can change; read the numbers.
    RecallResult:
      type: object
      required:
      - id
      - rank
      - occurredAt
      - content
      - artifact
      - sources
      additionalProperties: false
      properties:
        id:
          type: string
          format: uuid
        rank:
          type: integer
          minimum: 1
        occurredAt:
          type: string
          format: date-time
        content:
          type: string
        artifact:
          $ref: '#/components/schemas/RecallArtifact'
        sources:
          type: array
          items:
            $ref: '#/components/schemas/RecallSource'
  headers:
    RequestId:
      description: Server-generated id of this call, beginning with req_. Present on every /api/v1 response. The console's Requests screen lists the call under it.
      schema:
        type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Project API key beginning with past_sk_.
    managementKeyAuth:
      type: http
      scheme: bearer
      description: Management key beginning with past_mk_. One per organization, created from Settings in the console.
    agentTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Agent access token for one person, issued by https://sso.past.dev after the person approves the agent. https://api.past.dev/auth.md gives the procedure. The operation names the scope it asks for: memory:read or memory:write. Send X-Past-Project with the project slug; without it, the only live project of the organization is used, and an organization with two or more returns 400 project-required. Managed service only.'
x-refined-from:
- past-dev-openapi.json
- past-dev.json