# API Access

EVd3x provides a read-only external API under `/api/v1` so people and other agents can retrieve grounded analysis data safely and consistently.

## Authentication

Every `/api/v1/*` data endpoint requires an API key.

- Primary header: `Authorization: Bearer <API_KEY>`
- Secondary header: `X-API-Key: <API_KEY>`

Admin key management endpoints require:

- `X-Admin-Token: <ADMIN_TOKEN>`

## Response envelope (all v1 endpoints)

All `/api/v1/*` responses use this stable envelope:

```json
{
  "data": {},
  "meta": {
    "api_version": "v1",
    "generated_at": "2026-04-15T00:00:00+00:00",
    "source_endpoint": "/api/pathway",
    "path": "/api/v1/network/search",
    "method": "GET"
  },
  "warnings": [],
  "error": null
}
```

- `data`: endpoint payload
- `meta`: trace and version fields
- `warnings`: non-fatal caveats
- `error`: machine-readable error object (or `null`)

## Core endpoint catalog

### Network and query entrypoints

- `GET|POST /api/v1/network/search`
- `GET /api/v1/reverse/disease`
- `GET /api/v1/reverse/cell-communication`

### Detail and module endpoints

- `GET /api/v1/details`
- `GET /api/v1/pathways/enrichment`
- `GET /api/v1/disease/analysis`
- `GET /api/v1/ev/evidence`
- `POST /api/v1/cell-specificity`
- `POST /api/v1/cell-communication`
- `GET /api/v1/lr/analysis`
- `GET /api/v1/ppi/network`
- `GET /api/v1/platform/stats`

### API schema and quick reference

- `GET /api/v1/openapi.json`
- `GET /api/v1/docs`

## Key lifecycle (admin-generated)

### Generate key

```bash
curl -X POST "$HOST/api/v1/admin/keys/generate" \
  -H "Content-Type: application/json" \
  -H "X-Admin-Token: $ADMIN_TOKEN" \
  -d '{"owner":"research-bot","scopes":["read"],"rate_limit_per_min":120}'
```

### List keys

```bash
curl "$HOST/api/v1/admin/keys" \
  -H "X-Admin-Token: $ADMIN_TOKEN"
```

### Revoke key

```bash
curl -X POST "$HOST/api/v1/admin/keys/<KEY_ID>/revoke" \
  -H "X-Admin-Token: $ADMIN_TOKEN"
```

## Request examples

### 1) Search network from query

```bash
curl "$HOST/api/v1/network/search?mode=single&query=SNCA&direction=both&top_n=30" \
  -H "Authorization: Bearer $API_KEY"
```

### 2) Fetch lightweight details

```bash
curl "$HOST/api/v1/details?id=SNCA&type=Gene&sections=summary,annotation,ev_status,metrics&compact=1" \
  -H "Authorization: Bearer $API_KEY"
```

### 3) EV evidence-first retrieval

```bash
curl "$HOST/api/v1/ev/evidence?disease=Parkinson%20Disease&top_k=12" \
  -H "Authorization: Bearer $API_KEY"
```

### 4) Python client

```python
import requests

HOST = "https://evd3x.com"
headers = {"Authorization": "Bearer <API_KEY>"}

r = requests.get(
    f"{HOST}/api/v1/network/search",
    params={"mode": "single", "query": "SNCA", "direction": "both", "top_n": 30},
    headers=headers,
    timeout=60,
)
payload = r.json()
print(payload["meta"], payload["warnings"])
```

## Error semantics

- `401`: missing/invalid key
- `403`: disabled key
- `429`: key rate-limited (`Retry-After` header present)
- `5xx`: upstream/internal failure

Error payload example:

```json
{
  "data": null,
  "meta": {"api_version": "v1"},
  "warnings": [],
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for this API key.",
    "retry_after_seconds": 24
  }
}
```

## Agent usage pattern (recommended)

1. Start with `/api/v1/network/search`.
2. Pull focused details with `/api/v1/details` using targeted `sections`.
3. Request only needed analysis modules (`pathways`, `disease`, `ev evidence`, `cell`, `lr`, `ppi`).
4. Avoid broad fan-out until initial summary context is established.