# Overview

Edge exposes a REST API on the FastAPI backend. The canonical reference is auto-generated and served by the deployed instance.

## Live reference (on a running deployment)

| URL                              | Tool                 |
| -------------------------------- | -------------------- |
| `http://<host>/api/docs`         | Swagger UI           |
| `http://<host>/api/redoc`        | ReDoc                |
| `http://<host>/api/openapi.json` | Raw OpenAPI 3.1 spec |

On the demo: [`demo.edge.nyami.fr/api/docs`](https://demo.edge.nyami.fr/api/docs).

## Core endpoints

| Method | Path                         | Description                            |
| ------ | ---------------------------- | -------------------------------------- |
| `POST` | `/flows/execute`             | Execute a flow, returns `execution_id` |
| `GET`  | `/flows/progress/{id}`       | Stream execution progress events       |
| `GET`  | `/flows/results/{id}`        | Final execution results                |
| `POST` | `/ai/chat/completions`       | Proxied LLM chat completions           |
| `GET`  | `/datasets`                  | List datasets in scope                 |
| `POST` | `/datasets`                  | Create dataset                         |
| `POST` | `/datasets/{id}/import`      | Bulk-import goldens from Excel/CSV     |
| `GET`  | `/datasets/import/template`  | Download import template per use case  |
| `POST` | `/datasets/{id}/items/batch` | Batch create golden items              |
| `GET`  | `/evaluations`               | List evaluation runs                   |
| `GET`  | `/evaluations/{id}`          | Evaluation detail                      |
| `GET`  | `/health`                    | Liveness probe                         |

## 18 routers

`ai_proxy`, `datasets`, `datasets_import`, `evaluations`, `demo_data`, `admin_actions`, `access_control`, `flow`, `flow_templates`, `logs`, `users`, `settings`, `scheduled_jobs`, `chat`, `codebase`, `pb_mcp` (conditional), `chat_direct` (conditional), `debug_router` (dev only).

## Authentication

All endpoints except `/auth/login` and `/health` require a JWT in the `Authorization: Bearer <token>` header. Workspace-scoped endpoints additionally require an `X-Workspace-Id` header.

```bash
# Login
curl -X POST http://host/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"identity": "admin@example.com", "password": "..."}'
# → { "token": "eyJ...", "user": {...}, "workspaces": [...] }

# Authenticated call
curl http://host/api/datasets \
  -H 'Authorization: Bearer eyJ...' \
  -H 'X-Workspace-Id: ws_abc123'
```

## OpenAPI export

For tooling integration:

```bash
curl http://host/api/openapi.json > edge-openapi.json

# Generate a typed client (example: openapi-typescript)
npx openapi-typescript edge-openapi.json -o src/types/edge-api.d.ts
```

## Stability

| Path prefix                                                     | Stability                                                 |
| --------------------------------------------------------------- | --------------------------------------------------------- |
| `/flows/*`, `/datasets/*`, `/evaluations/*`, `/ai/*`, `/auth/*` | **Stable** — semver-tracked                               |
| `/health`, `/api/health`                                        | Stable                                                    |
| `/logs/*`, `/settings/*`, `/admin_actions/*`                    | Stable                                                    |
| `/debug_router/*`                                               | **Unstable** — dev-only, not present in production builds |
| `/pb_mcp/*`, `/chat_direct/*`                                   | Conditional — gated by env vars                           |

## Generated reference (planned)

A future build step will publish the OpenAPI spec as a static reference site under this section, refreshed per release. Today, point to a running instance.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.edge.nyami.fr/api-reference/index.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.