# Evidence API HTTP reference

`POST /v1/search` is available as a hosted, read-only endpoint at `https://evidence8.com/v1/search`. It searches the public index bundled with the current site deployment; it does not search private or locally ingested evidence. It uses deterministic lexical retrieval, accepts requests without an API key, and is rate limited to 60 requests per minute per IP address. Queries are processed for search and are not written to shared workspace request history.

`GET /v1/assets/{id}` also exposes public record metadata. Other workspace API routes are available only from a local development API at `127.0.0.1:8787`; they are not exposed as hosted endpoints. The local server binds to loopback. A local stdio MCP server is available for agents running on the same machine as an index; there is no hosted MCP transport. See [Connect agent](/connect-agent).

## `GET /v1/corpora`

Returns `{ "data": [...] }`. Each entry describes a corpus available or tracked in this workspace; fields can include `slug`, `name`, `status`, `visuals`, `sourceUrl`, `collectionMode`, `rightsProfile`, and a short `ledger` summary. Availability and indexed visual counts are workspace-specific. Check this endpoint before searching.

```sh
curl http://127.0.0.1:8787/v1/corpora
```

## `POST /v1/search`

Request JSON:

```json
{
  "query": "US unemployment rate UNRATE",
  "corpus": "macro-public-data",
  "candidateLimit": 5
}
```

`query` is required and can be up to 500 characters. `corpus` is optional and defaults to `all`. `candidateLimit` is optional and defaults to `5`; it must be an integer from 1 to 10. The JSON request body is limited to 16 KiB.

```sh
curl https://evidence8.com/v1/search \
  -H 'content-type: application/json' \
  -d '{"query":"US unemployment rate UNRATE","corpus":"macro-public-data","candidateLimit":5}'
```

Successful responses have `status: "ok"`, `results`, `total`, `selected`, `retrieval`, `timing`, and `usage`. No-match responses have `status: "no_match"`, a reason/message, and an empty `results` array. An empty query returns `status: "error"`; invalid JSON returns HTTP 400. The hosted endpoint is unauthenticated and returns candidates only from the public index.

`retrieval.mode` is `deterministic-lexical`; `model` is null and `reasoning` is false. Search rejects candidates missing an explicitly requested country and requires at least 0.62 coverage of the remaining query keywords. Country aliases such as US/USA and UK/Britain are supported; country comparisons require every requested country. Geography is taken from the individual visual’s metadata, not a publisher name or document-wide search hints.

Result `score` is query-specific keyword coverage, not a probability or a semantic accuracy guarantee. The original index score is preserved in `assetScore`. The `relevance` object includes `method`, `score`, `matchedTerms`, `missingTerms`, `requiredGeographies`, and `probability: null`. `retrieval.scoreType` is `lexical-coverage`. The result limit is a maximum; search may return fewer candidates or `no_match` rather than padding with weak matches. Response asset fields vary by source. Read [metadata guidance](/docs/metadata.md) and verify the original source.

## Asset records

When present, `asset.metadata` follows the `evidence.asset-metadata.v1` envelope. Key groups include:

- `identity`: asset ID, visual type, exposure state.
- `agent`: grounded summary and structured query hints; claim support can remain `not_evaluated`.
- `provenance`: publisher, source document, source URLs, page, and dates when known.
- `delivery`: asset/data URLs, rights label, delivery mode, and availability.
- `quality`: structural validation and separate semantic-inspection state.

Missing or unknown values must remain unknown. Structural validation does not mean the visual has been semantically reviewed. See the [full metadata notes](/docs/metadata.md).

## Evidence Extend (local only)

`GET /v1/capabilities` reports Extend availability and trusted domains. `POST /v1/extend/search` requires `Authorization: Bearer <OpenAI API key>` and JSON `{ "query": "energy demand chart", "sourceUrl": "https://www.iea.org/reports/..." }`; omit `sourceUrl` for discovery. The response is SSE: `progress`, `candidate`, then `complete`. Results preserve provenance, AI inspection state, uncertainty, and `expiresAt`; completion exposes `partial`, `reason`, and `warnings`. Close the stream to cancel. Accepted candidates remain available temporarily.

`GET /v1/extend/assets/:id` returns metadata; append `/content` for PNG pixels. Temporary evidence expires after 24 hours (HTTP 410), is not indexed, and does not grant redistribution rights. Extend uses your OpenAI API account and is unavailable in the public static search deployment.


## `GET /v1/assets/{id}` (hosted)

Returns `{ "data": { ... } }` for an indexed public visual, with absolute delivery URLs, the original source, and available provenance/rights metadata. Missing public IDs return 404. See the [OpenAPI contract](/openapi.json).

## Request measurement

Hosted search JSON includes `requestId`. Search and record responses include `X-Evidence-Request-Id` and `X-Evidence-Analytics` (`recorded` or `unavailable`). Sanitized server events retain status, candidate IDs, and latency without raw query text, IP addresses, credentials, or cookies. Public page and selected image fetches are recorded separately at the edge. User-agent bot labels are unverified claims. Audit traffic is separated from other requests. This does not reveal external search impressions, all citations, result acceptance, team retention, or payment.