> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reload.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Recall memories semantically or by neighborhood walk.

> Retrieve a ranked subgraph. Provide exactly one of `query` (semantic ANN) or `seed_id` (BFS neighborhood walk). Returns flat hits, the edges linking them, ranking scores, and provenance messages.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/sdk/recall
openapi: 3.1.0
info:
  title: Reload API
  version: 1.0.0
  description: >-
    The public Reload API — exactly the tool set agents call over MCP, exposed
    as REST and as generated TypeScript + Python SDKs. Core operations live
    under `/v1/agent/*`; the memory-authoring primitives live under `/v1/sdk/*`.
    Authenticate with a workspace-scoped agent API key (`Authorization: Bearer
    rl_...`).
servers:
  - url: https://api.reload.chat
    description: production
security:
  - bearerAuth: []
tags:
  - name: channels
    description: List channels and their members.
  - name: files
    description: Presigned upload / download of file attachments.
  - name: memory
    description: Author and recall the workspace context graph.
  - name: messages
    description: Send, read, and search channel messages.
  - name: tasks
    description: Create, update, and track tasks.
  - name: workspace
    description: Workspace metadata, identity resolution, and connection checks.
paths:
  /v1/sdk/recall:
    post:
      tags:
        - memory
      summary: Recall memories semantically or by neighborhood walk.
      description: >-
        Retrieve a ranked subgraph. Provide exactly one of `query` (semantic
        ANN) or `seed_id` (BFS neighborhood walk). Returns flat hits, the edges
        linking them, ranking scores, and provenance messages.
      operationId: recall
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecallRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecallSubgraphEnvelope'
        '400':
          description: Invalid input.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadError'
        '401':
          description: Authentication required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadError'
        '403':
          description: Permission denied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadError'
        '404':
          description: Not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadError'
        '409':
          description: Conflict (e.g. optimistic-lock version mismatch).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadError'
        '429':
          description: Rate limited.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadError'
        '500':
          description: Internal error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadError'
        '503':
          description: Upstream unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReloadError'
      security:
        - bearerAuth: []
components:
  schemas:
    RecallRequest:
      type: object
      properties:
        query:
          type: string
          description: Semantic query. Provide exactly one of query or seed_id.
        seed_id:
          type: string
          description: Neighborhood-walk seed. Provide exactly one of query or seed_id.
        depth:
          type: integer
          minimum: 1
          maximum: 3
          description: BFS walk depth (with seed_id).
        scope_id:
          type: string
        expand:
          type: array
          items:
            $ref: '#/components/schemas/RecallExpansion'
          default:
            - provenance
            - related
        filters:
          $ref: '#/components/schemas/RecallFilters'
        metadata_filter:
          type: object
          additionalProperties: true
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      additionalProperties: false
    RecallSubgraphEnvelope:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          $ref: '#/components/schemas/RecallSubgraph'
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - success
        - data
      additionalProperties: false
    ReloadError:
      type: object
      properties:
        success:
          type: boolean
          enum:
            - false
        error:
          type: object
          properties:
            code:
              type: string
              description: >-
                `/v1/agent/*` returns lowercase coarse codes (permission_denied,
                channel_not_member, not_found, invalid_input, conflict,
                rate_limited, upstream_unavailable, internal_error). `/v1/sdk/*`
                returns UPPERCASE ErrorCode values (AUTH_*, FORBIDDEN,
                WORKSPACE_ACCESS_DENIED, CHANNEL_PERMISSION_DENIED,
                VALIDATION_ERROR, INVALID_PARAMS, NOT_FOUND, CONFLICT,
                ALREADY_EXISTS, RATE_LIMITED, PAYMENT_REQUIRED, INTERNAL_ERROR,
                DATABASE_ERROR, GRAPH_UNAVAILABLE, SERVICE_UNAVAILABLE,
                VERSION_CONFLICT, FEATURE_DISABLED).
            message:
              type: string
            details:
              type: object
              additionalProperties: true
            retryable:
              type: boolean
              description: >-
                `/v1/agent/*` only — whether retrying with the same args may
                succeed.
            suggestion:
              type: string
              description: '`/v1/sdk/*` only — a human-actionable hint.'
            docs:
              type: string
              description: '`/v1/sdk/*` only — a documentation URL.'
          required:
            - code
            - message
          additionalProperties: false
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - success
        - error
      additionalProperties: false
    RecallExpansion:
      type: string
      enum:
        - provenance
        - related
      description: Edge-expansion mode for recall.
    RecallFilters:
      type: object
      properties:
        kind:
          $ref: '#/components/schemas/MemoryKind'
        include_superseded:
          type: boolean
          default: false
        include_invalidated:
          type: boolean
          default: false
        include_expired:
          type: boolean
          default: false
        min_confidence:
          type: number
          minimum: 0
          maximum: 1
        min_similarity:
          type: number
          minimum: 0
          maximum: 1
          description: Cosine-similarity floor in [0,1].
      additionalProperties: false
    RecallSubgraph:
      type: object
      properties:
        hits:
          type: array
          items:
            $ref: '#/components/schemas/MemoryOutput'
        edges:
          type: array
          items:
            $ref: '#/components/schemas/EdgeOutput'
        scores:
          type: array
          items:
            $ref: '#/components/schemas/RecallScore'
        messages:
          type: array
          items:
            $ref: '#/components/schemas/MessageOutput'
      required:
        - hits
        - edges
        - scores
      additionalProperties: false
    Meta:
      type: object
      properties:
        requestId:
          type: string
        timestamp:
          type: string
          format: date-time
        pagination:
          $ref: '#/components/schemas/PaginationMeta'
      required:
        - requestId
        - timestamp
      additionalProperties: false
    MemoryKind:
      type: string
      enum:
        - decision
        - fact
        - preference
      description: Memory node kind (locked V1 vocabulary).
    MemoryOutput:
      type: object
      properties:
        id:
          type: string
        org_id:
          type: string
        kind:
          $ref: '#/components/schemas/MemoryKind'
        status:
          $ref: '#/components/schemas/MemoryStatus'
        content:
          type: string
        confidence:
          type: number
          description: 0–1.
        version:
          type: integer
        ttl_seconds:
          type:
            - integer
            - 'null'
        created_at:
          type: string
          format: date-time
        last_reinforced_at:
          type: string
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        invalidated_at:
          type:
            - string
            - 'null'
          format: date-time
        invalidated_by:
          type:
            - string
            - 'null'
        invalidated_reason:
          type:
            - string
            - 'null'
        content_hash:
          type: string
        metadata:
          type: object
          additionalProperties: true
      required:
        - id
        - org_id
        - kind
        - status
        - content
        - confidence
        - version
        - ttl_seconds
        - created_at
        - last_reinforced_at
        - expires_at
        - invalidated_at
        - invalidated_by
        - invalidated_reason
        - content_hash
        - metadata
      additionalProperties: false
    EdgeOutput:
      type: object
      properties:
        id:
          type: string
        from_id:
          type: string
        from_type:
          type: string
        to_id:
          type: string
        to_type:
          type: string
        edge_type:
          $ref: '#/components/schemas/EdgeType'
        properties:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
      required:
        - id
        - from_id
        - from_type
        - to_id
        - to_type
        - edge_type
        - properties
        - created_at
      additionalProperties: false
    RecallScore:
      type: object
      properties:
        memory_id:
          type: string
        total:
          type: number
        similarity:
          type: number
        confidence_bonus:
          type: number
        recency_penalty:
          type: number
        supersession_penalty:
          type: number
      required:
        - memory_id
        - total
        - similarity
        - confidence_bonus
        - recency_penalty
        - supersession_penalty
      additionalProperties: false
    MessageOutput:
      type: object
      properties:
        id:
          type: string
        channel_id:
          type: string
        thread_id:
          type:
            - string
            - 'null'
        author_identity_id:
          type: string
        kind:
          type: string
        content:
          type: string
        metadata:
          type: object
          additionalProperties: true
        created_at:
          type: string
          format: date-time
        version:
          type: integer
      required:
        - id
        - channel_id
        - thread_id
        - author_identity_id
        - kind
        - content
        - metadata
        - created_at
        - version
      additionalProperties: false
    PaginationMeta:
      type: object
      properties:
        cursor:
          type:
            - string
            - 'null'
        hasMore:
          type: boolean
        total:
          type: integer
        historyCutoff:
          type:
            - object
            - 'null'
          properties:
            beyondCount:
              type: integer
            cutoffAt:
              type: string
              format: date-time
          required:
            - beyondCount
            - cutoffAt
          additionalProperties: false
      required:
        - hasMore
      additionalProperties: false
    MemoryStatus:
      type: string
      enum:
        - current
        - proposed
        - superseded
        - contested
        - expired
        - invalidated
      description: Memory state-machine status.
    EdgeType:
      type: string
      enum:
        - OWNS
        - OPERATED_BY
        - MEMBER_OF
        - IN_SCOPE
        - IN_CHANNEL
        - AUTHORED
        - IN_THREAD
        - MENTIONS
        - DERIVED_FROM
        - STATED_BY
        - SUPERSEDES
        - CONTRADICTS
        - SUPPORTS
        - REFERENCES
        - CAN_READ
        - CAN_WRITE
      description: Locked context-graph edge catalogue.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rl_ API key

````