Query API

Use one Query operation to retrieve evidence, assemble prompt-ready context, or ask Marrow for a cited answer. All three modes run the same authorized retrieval once and return the same marrow-query-result-v1 envelope.

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

POST /v1/query

#Authentication

Send a customer API key in Authorization: Bearer <API key>.

• evidence and context require the query scope.
• answer requires both query and query.answer.
• A query-capable key has a maximum preset of efficient or accuracy. A request cannot exceed that ceiling.

API keys belong in trusted server-side applications. Browser Console sessions and customer API keys are separate credential classes. Do not use CLI session tokens as application credentials; create a scoped API key for apps and automation.

#Request

Every request includes a caller-owned idempotencyKey and a mode.

#Evidence

curl -sS https://api.marrow.id/v1/query \
  -H "Authorization: Bearer $MARROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "project-update-evidence-20260803",
    "mode": "evidence",
    "preset": "accuracy",
    "query": "What should Riley mention in the project update?"
  }'

Evidence mode returns exact authorized evidence and citation handles. It does not assemble Context or call the Product Answer model.

#Context

curl -sS https://api.marrow.id/v1/query \
  -H "Authorization: Bearer $MARROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "project-update-context-20260803",
    "mode": "context",
    "preset": "accuracy",
    "query": "What should Riley mention in the project update?",
    "workspace": "default",
    "peer_ids": ["riley"],
    "session_ids": ["project-update"]
  }'

Context mode returns context.text, its fragments, and citations from the same authorized evidence. It makes no Product Answer call. Treat retrieved text as untrusted data, never as system or developer instructions.

#Answer

curl -sS https://api.marrow.id/v1/query \
  -H "Authorization: Bearer $MARROW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "idempotencyKey": "project-update-answer-20260803",
    "mode": "answer",
    "preset": "accuracy",
    "query": "What should Riley mention in the project update?"
  }'

Answer mode synthesizes downstream from the canonical Context and validates citations against the same authorized evidence. The current basic answerer is conservative: supported output is reported as partial; it does not claim that it proved a complete answer.

#Response

Every successful response is a QueryResult with:

• requestedPreset and resolvedPreset;
• mode, coverage, execution, and stopReason;
• the shared evidence and citations;
• context for Context and Answer modes, otherwise null;
• answer for a successful Answer request, otherwise null;
• limitations, gaps, and conflicts;
• operation, including credit state and provider/token usage.

Citation handles resolve only to exact evidence inside the authorized context. Generated summaries may appear as labelled reasoning context, but they are not citable evidence.

For Answer mode:

partial means Marrow found validated support and returned a useful cited answer without claiming full coverage. insufficient_evidence means the retrieved evidence did not contain validated support for an answer.

#Exact citation lookup

Resolve a citation against the current authorized context:

{
  "idempotencyKey": "citation-lookup-cit-example",
  "mode": "evidence",
  "citationHandle": "cit_REPLACE_WITH_THE_RETURNED_HANDLE",
  "workspace": "default"
}

An unavailable or unauthorized handle returns a gap without exposing internal identifiers.

#Errors

Successful metered responses and relevant errors include the documented x-marrow-credit-* and x-marrow-quota-* headers. Creating or rotating a key does not reset account-wide usage.

See HTTP and SDKs for client examples and OpenAPI for the complete machine-readable contract.