Get evidence

Attributed quotes for a scope - a signal, one or more themes, a study, or specific source items. At least one scope is required; multiple scopes intersect, so each extra id narrows the read. Optionally include counter-evidence.

GET/v1/evidence

Example

curl -X GET "https://silent-viper-157.convex.site/v1/evidence" \  -H "Authorization: Bearer $ASKENGINE_API_KEY"

Query Parameters

signalId?string

Scope to a signal's evidence.

themeIds?string

Comma-separated theme ids (max 50).

studyId?string

Scope to a study.

sourceItemIds?string

Comma-separated source-item ids (max 50).

evidenceIds?string

Comma-separated evidence ids (max 50) for a direct lookup of quotes you already hold — ask citations, search hits, packet tasters. Kind filtering does not apply to a by-id read: counter-evidence resolves without includeCounterEvidence. Ids that do not resolve — malformed, unknown, or excluded by another scope — come back in unresolvedIds; the rest return normally.

includeCounterEvidence?boolean

Include counter-evidence in the packet.

maxItems?integer

Maximum evidence items to return. Defaults to 20; maximum 100.

Default20Range1-100

cursor?string

The cursor the previous page's packet handed back.

Response

{  "data": {    "items": [      {        "evidenceId": "ev_001",        "kind": "evidence",        "quote": "I gave up twice before I figured out where to add my API key.",        "themeId": "thm_setup",        "themeLabel": "Setup friction",        "studyId": "study_789",        "studyName": "Onboarding interviews Q4",        "sourceItemId": "src_a1",        "participantName": "Ada L.",        "timeInCallSecs": 412,        "capturedAt": 1764453600000      }    ],    "scope": {      "themeIds": [        "thm_setup"      ],      "studyIds": [        "study_789"      ]    },    "distinctParticipants": 6,    "total": 8,    "cursor": null  }}