Evidence-backed query

Returns ranked typed records plus the source-note excerpts each record was extracted from. Use query (POST /v1/query) when you need cited, source-grounded answers rather than free-text generation.

Input is a natural-language question. Marrow embeds it with Voyage, ranks records by vector distance over the authenticated account's graph, and joins each record's extracted-from source notes.

• Every result is typed (note, claim, position, project, entity).
• Every result carries a confidenceScore, a sourceKind, and a sourceRunId.
• Every claim or typed entity returns the source-note excerpts that substantiate it.
• The response is retrieval-only. Marrow returns the records that should ground an answer, not the answer text itself.

#Example

{
  "query": "What evidence supports their cross-functional delivery work?",
  "limit": 5,
  "evidenceLimit": 3
}

Every response carries four parts:

#Results

Ranked typed records, ready to cite directly.

[
  {
    "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 into Northstar …",
    "sourceKind": "interview",
    "sourceRunId": "f1a3…",
    "confidenceKind": "asserted",
    "confidenceScore": 0.92,
    "facets": ["cross-functional-delivery", "onboarding-rollout"],
    "evidenceNotes": [ /* see below */ ]
  }
]

#Evidence notes

For every result, Marrow returns the source-note excerpts the record was extracted from. Each note carries its source kind, source run, confidence, and the typed relationship.

[
  {
    "id": "9b2c…",
    "excerpt": "On the Northstar team, I drove the onboarding rollout into the production launch pipeline …",
    "sourceKind": "interview",
    "sourceRunId": "f1a3…",
    "confidenceKind": "asserted",
    "confidenceScore": 0.95,
    "facets": ["cross-functional-delivery"],
    "relationship": "extracted-from"
  }
]

relationship is either self (the result is itself a note) or extracted-from (the note is upstream evidence for a claim or entity).

#Mode and target

The response declares which retrieval mode was used and which node types were searched.

{
  "mode": "topical",
  "target": "all",
  "model": "voyage-4-large",
  "dimensions": 1024
}

• mode is topical by default; pass "style": true to switch to style embeddings, which rank by writing voice rather than topic.
• target constrains the search to a single node type (note, claim, position, project, entity) when you only want a specific shape.

#Warnings

Marrow surfaces anything the calling agent should know about (unindexed records, missing embeddings, anchor mismatches) so cited answers can carry caveats.

{ "warnings": ["3 candidate claims had no embedding and were excluded from ranking."] }

#Style-aware query

Switch the embedding space from topical to stylistic to rank records by how they sound rather than what they're about:

{ "query": "concise technical prose", "style": true, "target": "note" }

This is how downstream writing agents pull voice exemplars without prompt-stuffing the corpus.

#What you get back

#Limits

limit caps result records at 20; evidenceLimit caps evidence notes per result at 10. The defaults (5 and 3) are tuned for compact agent prompts.

#Scope

Requires an API key with scope query. See the Query API Reference for the full request and response schema.