Marrow
Docs Sign in

Query API

Use the Query API to retrieve context from records added to Marrow. For normal CLI queries, run marrow query "<question>".

Base URL: https://api.marrow.id

POST /v1/query

Authentication

Direct HTTP integrations use a customer API key:

Scheme Header
Bearer Authorization: Bearer <API key>

API key must include scope query.

The 1.0 CLI reads MARROW_API_KEY for product commands, including marrow query "<question>". marrow auth login creates a separate account-management session for key lifecycle work on macOS. Do not use CLI session tokens as application credentials; create a scoped API key for apps and automation.

Request body

Field Type Required Default Notes
query string yes Non-empty natural-language question
limit integer no 5 Max results returned. 1 ≤ limit ≤ 20
evidenceLimit integer no 3 Max supporting excerpts per result. 1 ≤ evidenceLimit ≤ 10

Response: 200 OK

{
  "schemaVersion": "marrow-evidence-query-v2",
  "generatedAt": "2026-05-14T16:31:00Z",
  "query": "What evidence supports their cross-functional delivery work?",
  "answer": {
    "status": "partial",
    "text": "On the Northstar team, I drove the onboarding rollout across support, success, and engineering. [1]",
    "citations": [
      {
        "citationId": 1,
        "excerpt": "On the Northstar team, I drove the onboarding rollout across support, success, and engineering.",
        "sourceLabel": "Source excerpt",
        "support": "quotation",
        "charOffsetStart": 0,
        "charOffsetEnd": 95
      }
    ],
    "limitations": [
      "The answer only uses the excerpts shown below.",
      "Marrow found relevant cited excerpts, but it could not verify that they fully answer every part of the question."
    ]
  },
  "results": [
    {
      "rank": 1,
      "title": "Led cross-functional delivery of the Northstar onboarding rollout.",
      "snippet": "Avery drove the rollout of the onboarding flow …",
      "evidence": [
        {
          "citationId": 1,
          "excerpt": "On the Northstar team, I drove the onboarding rollout across support, success, and engineering.",
          "sourceLabel": "Source excerpt",
          "support": "quotation",
          "charOffsetStart": 0,
          "charOffsetEnd": 95
        }
      ]
    }
  ],
  "warnings": []
}

Field reference

Field Type Description
schemaVersion string Always marrow-evidence-query-v2
answer.status enum "partial" when Marrow found relevant cited excerpts but could not verify a complete answer; "insufficient_evidence" when it could not verify enough support
answer.text string Compact extractive answer text. Factual answer sentences are copied from returned evidence and cite citation numbers
answer.citations[] object[] Public citations with citationId, excerpt, and sourceLabel
*.citations[].support / results[].evidence[].support enum? Typed support when applicable: quotation, compression, or inference. An internal unsupported verdict is never returned as evidence
*.citations[].charOffsetStart / charOffsetEnd integer? Optional non-negative source-text locator. The two fields are returned together or omitted together
answer.limitations string[]? Caveats about missing, thin, or truncated extractive evidence
results[].title string Short result title
results[].evidence[] object[] Public supporting excerpts behind a result, with the same citation fields described above
warnings string[] Retrieval caveats

Errors

Code error.code Reason
401 unauthorized Missing, malformed, or revoked product credential
403 forbidden API key is valid but lacks scope query
402 account_credits_exhausted Account does not have enough Marrow credits for the query
400 validation_error Body failed validation; see error.issues
429 rate_limited Per-key request window exceeded. See retry-after and x-ratelimit-* headers

All errors share the envelope:

{
  "schemaVersion": "marrow-api-error-v1",
  "requestId": "request-id",
  "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.

Credit headers

Successful query responses and credit errors include:

x-marrow-credit-cost: 1
x-marrow-credit-remaining: 349
x-marrow-credit-monthly-remaining: 99
x-marrow-credit-onboarding-remaining: 250
x-marrow-credit-monthly-period: 2026-05-01

Credit balances are reported per account and may include monthly and onboarding segments. Monthly credits are debited before onboarding credits.

Credit headers report only account credit impact for the request.

CLI mapping

marrow query "What evidence supports the cross-functional delivery work?"
marrow query "What evidence supports the cross-functional delivery work?" --json

See Marrow CLI for CLI setup.