# API Access

EVd3x exposes a read-only external API under `/api/v1` for programmatic, source-attributed retrieval.

## Authentication

All data endpoints require an API key.

- `Authorization: Bearer <API_KEY>`
- `X-API-Key: <API_KEY>` (alternate)

Admin key management endpoints require:
- `X-Admin-Token: <ADMIN_TOKEN>`

## Response envelope

All `/api/v1/*` endpoints return:

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

## Endpoint map

### Query and reverse entrypoints

- `GET|POST /api/v1/network/search` -> `/api/pathway`
- `GET /api/v1/reverse/disease` -> `/api/agent/reverse_disease`
- `GET /api/v1/reverse/cell-communication` -> `/api/agent/reverse_cell_comm`

### Analysis and detail endpoints

- `GET /api/v1/details` -> `/api/details`
- `GET /api/v1/pathways/enrichment` -> `/api/pathway_enrichment`
- `GET /api/v1/disease/analysis` -> `/api/collective_disease_analysis`
- `GET /api/v1/ev/evidence` -> `/api/agent/reverse_evidence`
- `POST /api/v1/cell-specificity` -> `/api/cell_specificity`
- `POST /api/v1/cell-communication` -> `/api/cell_communication_v2`
- `GET /api/v1/lr/analysis` -> `/api/ligand_receptor_analysis`
- `GET /api/v1/ppi/network` -> `/api/ppi_network`
- `GET /api/v1/platform/stats` -> `/api/platform_stats`

### Schema and quick reference

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

## Key lifecycle (admin)

### Generate

```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

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

### Revoke

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

## Request examples

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

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

```python
import requests

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

resp = requests.get(
    f"{HOST}/api/v1/platform/stats",
    headers=headers,
    timeout=30,
)
print(resp.json()["meta"])
```

## Error semantics

- `401`: missing or invalid API key
- `403`: disabled API key
- `429`: rate limit exceeded
- `5xx`: internal or upstream failure