# Evidence API agent integration guide

Evidence API retrieves candidate visual evidence—such as charts, tables, and filing-derived visuals—for financial research workflows. Each candidate can carry a source trail and available date, period, context, and rights metadata so an analyst can inspect it before use.

## What an agent can do today

- Use the [search sandbox](/playground) to try a query in the browser.
- Call the hosted, read-only search endpoint at `https://evidence8.com/v1/search` to search the public index.
- Connect a local MCP-compatible agent to this checkout with the stdio server in `apps/mcp/server.mjs`.
- Use the CLI or other local HTTP API routes when running this project with access to its workspace and index.
- Inspect the available corpora before searching; coverage varies by workspace and is not exhaustive.

The hosted search endpoint is public and read-only: it searches only the public index bundled with the current deployment, requires no API key, and is rate limited to 60 requests per minute per IP address. Private and locally ingested evidence is not available through it. Public visual metadata is also available at `GET https://evidence8.com/v1/assets/{id}`. Other workspace operations and the MCP server remain local: the API binds to `127.0.0.1`, while MCP runs as a stdio process beside the index. For copyable client setup, see [Connect agent](/connect-agent).

## Typical workflow

1. An analyst asks a research question inside an existing research product.
2. That product sends the question and an optional corpus slug to Evidence API.
3. Evidence API returns matching candidates and their available source metadata.
4. The product shows the source and context; the analyst checks whether a candidate fits before citing, embedding, or redistributing it.

Do not present a retrieval match as a verified conclusion. Search is deterministic lexical matching, not model reasoning or semantic verification. A high score, successful metadata validation, or result status does not guarantee that a visual supports the analyst’s claim.

## Run locally

From a checkout of this project, install dependencies and start the web app and local API:

```sh
npm install
npm run dev
```

The browser app is served at `http://127.0.0.1:4173`; the local API listens at `http://127.0.0.1:8787`.

## Connect an MCP client

Install this project on the same machine as your local MCP client, then configure the client to launch the server with Node.js:

```json
{
  "mcpServers": {
    "evidence": {
      "command": "node",
      "args": ["/absolute/path/to/EvidenceVisual/apps/mcp/server.mjs"]
    }
  }
}
```

The server exposes `list_evidence_sources`, `search_visual_evidence`, and `get_visual_evidence`. Search is deterministic lexical retrieval. Results are candidates, not verified support for a claim. The client starts the process over stdio; do not run it as a network service.

List available corpora and search with the CLI:

```sh
npm run evidence -- corpora list
npm run evidence -- search "US unemployment rate UNRATE" --json
```

Or send a request to the hosted search endpoint:

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

The endpoint accepts `query` (required), `corpus` (optional; defaults to `all`), and `candidateLimit` (optional; defaults to 5). The response includes a `status`, a `results` array, and—when a candidate is returned—a `selected` result. Each asset’s exact fields vary with the source; inspect the asset’s metadata and original source rather than assuming every field is populated.

## Review a candidate safely

- Check the publisher, canonical source URL, document or series, and page or reporting period when available.
- Distinguish a publisher’s original chart from a visual derived from source data or filing facts.
- Review `delivery.rights` and the source’s terms separately; an accessible image is not automatically licensed for redistribution.
- Treat absent or unknown dates, vintage, visual meaning, and rights as unknown—not as positive assurances.
- If no result is returned, do not infer that the source contains no relevant evidence; it may simply be outside the current index or not match the lexical query.

See the [HTTP API reference](/docs/api-reference.md), [metadata guide](/docs/metadata.md), and [current corpus registry](/corpora).

## Evidence Extend (local, explicit opt-in)

Call `extend_visual_evidence` only when the user asks to search beyond indexed sources. Configure `OPENAI_API_KEY` locally and allow a 210-second tool timeout. This retrieves and inspects actual source visuals from a bounded set of trusted domains; it does not index the results. Results include provenance, reporting period, uncertainty, inspection state, and 24-hour expiry. `get_visual_evidence` can inspect a temporary Extend ID while it remains available. Provider usage belongs to the configured OpenAI API account. Hosted static search does not support Extend.

## Public discovery and request measurement

Read the [OpenAPI contract](/openapi.json) and explore the [evidence library](/evidence). Search and record responses include `X-Evidence-Request-Id`; search JSON also includes `requestId`. `X-Evidence-Analytics: recorded` means a sanitized request event was durably recorded; `unavailable` means recording failed. Events contain response status, returned asset IDs, and timing, not raw query text or credentials. Crawls and downloads do not establish use in an answer.