POST /api/v1/search — the same hybrid vector + keyword + entity ranking as Recall, returned as ranked memories without the LLM-written summary.

POST /api/v1/search and POST /api/v1/recall take the same request body and rank memories the same way. Search returns the ranked memories as items and stops there. Recall runs the same search and then asks a model to write a summary of the results, which adds seconds per call. Use search when your code, or an SDK such as Rail, builds its own prompt from the memories; use recall when you want the synthesized brief.

Set caller_agent_id to the agent the search runs as. It decides which agent-private memories are visible and whose trust and fleet the read is gated against, without filtering results to that agent's own memories. Available since open-source release backend-v2.47.0.

Authorization

APIKeyHeader

X-API-Key<token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

tenant_id*Tenant Id

fleet_ids?array<string>|null

query*Query

Length1 <= length <= 5000

filter_agent_id?string|null

caller_agent_id?|

Assert the agent identity this search runs as, WITHOUT filtering results to that agent's own memories (use filter_agent_id for that). Determines which scope_agent memories are visible and whose trust/fleet level the read is gated against. Ignored when the credential already carries an agent identity, which wins. An agent-scoped credential may only name itself.

memory_type_filter?|

Filter results to a single memory type. Valid values: fact, episode, decision, preference, task, semantic, intention, plan, commitment, action, outcome, cancellation, rule, insight.

status_filter?|

Restrict results to one status. When omitted, superseded memories are hidden: 'outdated' rows are excluded, and 'conflicted' rows are excluded unless they exactly match the query text. Their replacements are injected in their place. Pass an explicit status to bypass this and read the superseded rows directly.

valid_at?|

As-of time for the question (ISO 8601). Rows whose ts_valid_start is after this date are excluded and rows whose ts_valid_end is before it are down-weighted; relative dates in the query ('last month') are resolved against it. When the tenant's search.default_profile sets freshness_reference=1, freshness and the temporal window are ALSO measured from this time against each row's event time (ts_valid_start, else created_at) instead of from now() — the setting for backfilled corpora where ingest time carries no signal. Naive values are read as UTC.

top_k?Top K

Maximum results the query returns (1-200, default 5). Not the response ceiling: each returned outdated/conflicted row also carries its newest correction, injected beyond this budget and marked injected: true (with score: null), so a response holds at most 2*top_k items.

Default5

Range1 <= value <= 200

min_similarity?|

Per-request similarity floor (0.0-1.0) applied to the raw cosine; overrides the agent/tenant search-profile value for this call.

diagnostic?Diagnostic

Defaultfalse

Response Body

`application/json`

curl -X POST "https://loading/api/v1/search" \  -H "Content-Type: application/json" \  -d '{    "tenant_id": "string",    "query": "string"  }'

{
  "items": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "tenant_id": "string",
      "fleet_id": "string",
      "agent_id": "string",
      "agent_display_name": "string",
      "memory_type": "string",
      "title": "string",
      "content": "string",
      "weight": 0,
      "source_uri": "string",
      "run_id": "string",
      "metadata": {},
      "system_metadata": {},
      "created_at": "2019-08-24T14:15:22Z",
      "expires_at": "2019-08-24T14:15:22Z",
      "entity_links": [],
      "similarity": 0,
      "score": 0,
      "score_parts": {
        "vec_sim": 0,
        "fts_score": 0,
        "freshness": 0,
        "entity_boost": 0,
        "recall_boost": 0,
        "temporal_boost": 0,
        "status_penalty": 0
      },
      "injected": false,
      "subject_entity_id": "2f43e1a1-7cec-4ccf-9421-4ab19090ca45",
      "predicate": "string",
      "object_value": "string",
      "ts_valid_start": "2019-08-24T14:15:22Z",
      "ts_valid_end": "2019-08-24T14:15:22Z",
      "status": "active",
      "visibility": "scope_team",
      "recall_count": 0,
      "last_recalled_at": "2019-08-24T14:15:22Z",
      "supersedes_id": "8149cd94-4e90-4a99-91f5-a3e0f9b829dc",
      "superseded_by": [
        {
          "old_memory_id": "07606bd2-b9bc-468a-8200-790e8b7345cf",
          "old_status": "string",
          "reason": "string",
          "old_content_preview": "string",
          "direction": "canonical"
        }
      ],
      "confidence": 0,
      "is_inferred": false,
      "scope": {},
      "usage": {
        "memories_stored": 0,
        "memories_limit": 0,
        "writes_remaining": 0
      }
    }
  ],
  "recall_tracked": false,
  "diagnostic": {
    "retrieval_strategy": "string",
    "top_k_requested": 0,
    "min_similarity_applied": 0,
    "candidates_considered": 0,
    "returned": 0,
    "excluded_below_min_similarity": 0,
    "excluded_by_top_k_trim": 0,
    "search_params": {},
    "all_candidates": [],
    "entity_matches": 0,
    "entity_match_declined": false
  },
  "warnings": [
    {
      "code": "string",
      "message": "string",
      "details": {}
    }
  ]
}

{
  "detail": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

{
  "detail": "string",
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  }
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Search

Authorization

Request Body

Response Body

200application/json

401application/json

403application/json

422application/json

`application/json`

`application/json`

`application/json`

`application/json`