Marrow
Docs Log in Sign up

Query

Evidence-backed query against the authenticated account's graph. Returns ranked typed records plus the source-note excerpts each record was extracted from.

POST /v1/query

Authentication

Scheme Header
Bearer Authorization: Bearer <API key>

API key must include scope query.

Request body

Field Type Required Default Notes
query string yes Non-empty natural-language question
limit integer no 5 Max records returned. 1 ≤ limit ≤ 20
evidenceLimit integer no 3 Max evidence notes per record. 1 ≤ evidenceLimit ≤ 10
target string no "all" "all" | "note" | "claim" | "position" | "project" | "entity"
style boolean no false When true, ranks by note-style embeddings instead of topical embeddings
model string no server default Override the embedding model id

Response: 200 OK

{
  "schemaVersion": "marrow-evidence-query-v1",
  "generatedAt": "2026-05-14T16:31:00Z",
  "query": "What evidence supports their cross-functional delivery work?",
  "mode": "topical",
  "target": "all",
  "model": "voyage-4-large",
  "dimensions": 1024,
  "usage": { "totalTokens": 41 },
  "answer": { "status": "retrieval-only", "note": "Marrow returns evidence, not generated answer text." },
  "results": [
    {
      "rank": 1,
      "nodeType": "claim",
      "nodeId": "1f0e…",
      "score": 0.87,
      "distance": 0.13,
      "title": "Led cross-functional delivery of the Northstar onboarding rollout.",
      "snippet": "Avery drove the rollout of the onboarding flow …",
      "sourceKind": "interview",
      "sourceRunId": "f1a3…",
      "confidenceKind": "asserted",
      "confidenceScore": 0.92,
      "facets": ["cross-functional-delivery", "onboarding-rollout"],
      "evidenceNotes": [
        {
          "id": "9b2c…",
          "excerpt": "On the Northstar team, I drove the onboarding rollout …",
          "sourceKind": "interview",
          "sourceRunId": "f1a3…",
          "confidenceKind": "asserted",
          "confidenceScore": 0.95,
          "facets": ["cross-functional-delivery"],
          "relationship": "extracted-from"
        }
      ]
    }
  ],
  "warnings": []
}

Field reference

Field Type Description
schemaVersion string Always marrow-evidence-query-v1
mode string topical, style, or exact (term fallback when no vectors exist)
target string Echo of the target requested
model, dimensions string, integer Embedding model and vector dimensions used
usage.totalTokens integer? Token usage for the query embedding call, when reported by the provider
results[].nodeType enum note | claim | position | project | entity
results[].score number Higher is closer. Bounded to [0, 1] for cosine; raw for exact fallback
results[].confidenceScore number? [0, 1] if recorded on the row, otherwise null
results[].evidenceNotes[].relationship enum "self" or "extracted-from"
warnings string[] Retrieval caveats: unindexed records, missing vectors, anchor anomalies

Errors

Code error.code Reason
401 unauthorized Missing, malformed, or revoked API key
403 forbidden API key is valid but lacks scope query
422 validation_error Body failed Zod validation; see error.issues
429 rate_limit_exceeded Window exceeded. See retry-after header and x-ratelimit-* headers

All errors share the envelope:

{
  "schemaVersion": "marrow-api-error-v1",
  "requestId": "req_…",
  "error": { "code": "validation_error", "message": "…", "issues": [/* zod issues */] }
}

Rate limit headers

Authenticated responses include:

x-ratelimit-limit: 60
x-ratelimit-remaining: 57
x-ratelimit-reset: 2026-05-14T16:32:00Z

429 adds retry-after in seconds.

CLI mapping

npm run dev -- api query "What evidence supports the cross-functional delivery work?"

See Marrow CLI for the local equivalents.