Nicolas Cantu
088eab84b7
- Add ia_dev submodule (projects/smart_ide on forge 4nk) - Document APIs, orchestrator, gateway, local-office, rollout - Add systemd/scripts layout; relocate setup scripts - Remove obsolete nginx/enso-only docs from this repo scope
59 lines
2.3 KiB
Markdown
59 lines
2.3 KiB
Markdown
# 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 `.cursor/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.
|