# API — ia-dev-gateway (spécification)

Service prévu sous [`services/ia-dev-gateway/`](../../services/ia-dev-gateway/). Auth **`Authorization: Bearer`** avec `IA_DEV_GATEWAY_TOKEN`. Bind par défaut **`127.0.0.1`**, port par défaut **`37144`**.

## `GET /health`

**200** : `{ "status": "ok" }` (sans Bearer).

## `GET /v1/agents`

Liste les agents exposés par le registre `ia_dev` (fichiers de définition sous `.smartIde/agents/` ou équivalent documenté dans le fork).

**200** : `{ "agents": [ { "id", "name", "summary", "triggerCommands": string[] } ] }`

**401** : Bearer manquant ou invalide.

## `GET /v1/agents/{id}`

**200** : descripteur étendu : `id`, `name`, `role`, `inputs`, `outputs`, `rights`, `dependencies`, `scripts`, `risk`, `compatibleEnvs`.

**404** : agent inconnu.

## `POST /v1/runs`

Démarre une exécution (agent, script deploy, ou intention résolue).

**Corps JSON**

| Champ | Obligatoire | Description |
|-------|-------------|-------------|
| `agentId` | oui* | Identifiant agent (`*` requis si pas `scriptPath` — voir évolution schéma) |
| `projectId` | oui | Ex. `lecoffreio` — répertoire `projects/<projectId>/` sous `ia_dev` |
| `intent` | oui | Libellé d’intention (`ask`, `fix`, `deploy`, …) |
| `payload` | non | Objet JSON opaque pour le runner |
| `env` | non | `test` \| `pprod` \| `prod` — contrôle des scripts autorisés |

**200** : `{ "runId": "string", "status": "queued" | "running" }`

**403** : droit refusé pour `env` ou `projectId`.

**422** : corps invalide.

## `GET /v1/runs/{runId}`

**200** : `{ "runId", "status", "startedAt", "finishedAt"?, "exitCode"?, "summary"?, "error"? }`

**404** : run inconnu.

## `GET /v1/runs/{runId}/events`

**Server-Sent Events** (recommandé en v1) : lignes `data: {JSON}\n\n` avec types d’événements alignés sur [system-architecture.md](../system-architecture.md) (`started`, `tool_selected`, `script_started`, `model_called`, `waiting_validation`, `completed`, `failed`, `rolled_back`, `artifact_created`).

**401** / **404** selon le cas.

## Notes

- Les détails d’exécution réels (spawn process, Docker, SSH) restent dans le **runner** branché sur `IA_DEV_ROOT` ; cette API est le **contrat** pour l’orchestrateur et les UIs.
- Versionnement : préfixe `/v1/` pour évolutions compatibles.