Loading evidence and metric snapshots
Loading evidence and metric snapshots
API consumer journey
Read sanitized evidence as versioned JSON, keep each result bound to a frozen snapshot, and use exports or signed packets when another person must reproduce the same public inputs.
A snapshot freezes the admitted source cutoff, cohort, taxonomy, metric methods, and freshness policy. A request without a snapshot can resolve to a newer public snapshot later. Put the snapshot key in stored queries, citations, and exported filenames when you need a stable answer.
PostgreSQL means the route reads the durable data plane. Deterministic fixture means it returns synthetic records for local interaction tests. Production refuses fixture mode. The response metadata names the active mode, so a client can prevent fixture records from entering research output.
Source mode and freshness answer different questions. PostgreSQL data can still contain old source activity. A fixture record can be internally consistent while proving nothing about a provider.
First request
This example uses the snapshot shown above. The response is an envelope with public rows, pagination state, and metadata. Keep all three parts together.
base_url="https://YOUR-UPSTREAM-HOST"
curl --fail --show-error --include \
"$base_url/api/v1/research?snapshot=weekly-cutoff%3Apilot-live-v1%3A2026-08-17T16%3A00%3A00.000Z&limit=25"{
"data": [
"public rows"
],
"page": {
"nextCursor": "opaque value or null",
"hasMore": false,
"limit": 25
},
"meta": {
"snapshotId": "weekly-cutoff:pilot-live-v1:2026-08-17T16:00:00.000Z",
"sourceCutoff": "2026-08-17T16:00:00.000Z",
"taxonomyVersion": "513f67b1-9ea7-46cc-b713-d6ea30ffb93f",
"cohortVersion": "aac24f2b-1109-5deb-a608-1c3d55fb0ae6",
"sourceMode": "postgres",
"apiVersion": "v1"
}
}Collection reads accept a limit from 1 through 200. When page.hasMore is true, send the returned page.nextCursor back to the same endpoint with the same snapshot and filters. Treat the cursor as opaque. It is bound to its resource, snapshot, filter scope, and collection revision where that contract applies.
GET /api/v1/research?snapshot=weekly-cutoff:pilot-live-v1:2026-08-17T16:00:00.000Z&limit=25&cursor=<page.nextCursor>A stale or mismatched cursor returns a typed 400 response. Restart without the cursor after choosing the snapshot and filters you want.
Public JSON responses include a content-based ETag. Store it and send If-None-Match on the next request. An unchanged response returns 304 with no body. An ETag identifies response bytes. The snapshot key identifies the frozen research state. Keep both when they matter.
GET /api/v1/research?snapshot=weekly-cutoff%3Apilot-live-v1%3A2026-08-17T16%3A00%3A00.000Z&limit=25
If-None-Match: "<ETag from the first response>"
HTTP/1.1 304 Not ModifiedThese links use the current deployment. Add a snapshot parameter where the endpoint supports it and you need a stable historical read.
Scroll horizontally to inspect every column.
| Resource | Route | Use it for |
|---|---|---|
| Research | /api/v1/research | Filter public evidence-chain rows at one snapshot. |
| Evidence chains | /api/v1/evidence-chains | Read stages, relationship bases, and typed gaps. |
| Evidence | /api/v1/evidence | Read sanitized public source records and hashes. |
| Coverage | /api/v1/coverage | Separate collected, mapped, missing, stale, and unavailable states. |
| Benchmarks | /api/v1/benchmarks | Read public comparison context and source provenance. |
| Snapshots | /api/v1/snapshots | Choose a frozen source cutoff and method identity. |
| Reports | /api/v1/reports | Read published, superseded, and retracted report versions. |
The research export accepts the same snapshot and filters as the research read. JSON returns rows with the response metadata. CSV returns the rows and carries snapshot, cutoff, method, cohort, source mode, and query fingerprint values in X-Upstream-* headers. Store those headers beside the file.
Evidence-chain and report-version packet routes return deterministic signed ZIP files. The archive uses fixed ZIP metadata and sorted paths. It contains manifest.json, SHA256SUMS, and sanitized public inputs. Public JSON in the packet uses stable key ordering.
The Ed25519 signature covers the SHA-256 of the canonical manifest inventory. Verify the archive hash, file checksums, manifest hash, signature, and signing key ID. Packet integrity does not establish who controls the key. Compare the public key through a separate trusted channel.
An unqualified packet request redirects to a snapshot-qualified and signer-qualified URL when an eligible packet exists. Start from a published chain or report version so the interface supplies its exact version identifier.
Choose a published chainAPI errors use application/problem+json with type, title, status, detail, instance, and usually a stable code. A response can add fields that explain a conflict or validation failure. Branch on HTTP status and code. Log the detail for a person. A temporary 503 can include Retry-After.
{
"type": "https://accelerator-evidence.local/problems/invalid-page",
"title": "Invalid research page",
"status": 400,
"detail": "The cursor is malformed or belongs to another snapshot, filter set, or collection revision.",
"instance": "/api/v1/research",
"code": "invalid_page"
}The public contract excludes raw webhook bodies, analyst notes, credentials, private evidence, quarantined bundles, and signed storage URLs.
Inspect every public schema