# API

The representative surface is defined in `LEGATE_AGENT_BUILD_PLAN.md` Section 13.
Interactive docs are served at `/docs` (Swagger) and `/redoc` when the API runs.

## Implemented (Phase 1)

```
POST   /auth/register
POST   /auth/login
POST   /auth/refresh

GET    /workspaces            POST /workspaces            POST /workspaces/{id}/switch
GET    /members              POST /members/invite        PATCH /members/{id}/role
GET    /api-keys             POST /api-keys              DELETE /api-keys/{id}
GET    /audit

GET    /health
```

## Implemented (Phase 2 — agents + runs)

```
GET    /tools                                            # available built-in tools

GET    /agents              POST /agents
GET    /agents/{id}         PATCH /agents/{id}          DELETE /agents/{id}
POST   /agents/{id}/run                                  # returns run_id + stream_url

GET    /runs               GET  /runs/{id}             GET /runs/{id}/steps
WS     /runs/{id}/stream                                 # ?token=<access token>
```

Agent CRUD requires `build:write`; running requires `runs:execute`; reading runs
and the WebSocket stream require `read`. The stream replays persisted steps, then
pushes live `step` and `run.status` events until the run is terminal.

## Implemented (Phase 3 — knowledge / RAG)

```
GET    /knowledge-bases            POST /knowledge-bases
GET    /knowledge-bases/{id}       DELETE /knowledge-bases/{id}
POST   /knowledge-bases/{id}/documents     # multipart file upload -> async ingest
GET    /knowledge-bases/{id}/documents
GET    /documents/{id}             DELETE /documents/{id}
POST   /documents/{id}/reingest
POST   /knowledge-bases/{id}/search        # { query, top_k } -> citations
```

KB/document management requires `build:write`; listing and search require `read`.
Uploads are stored, then ingested asynchronously (parse → chunk → embed → upsert);
poll `GET /documents/{id}` for `status` (`pending`/`processing`/`ready`/`failed`).
Agents retrieve from the workspace's knowledge bases through the `kb.search` tool,
returning passages with their source document for citation.

## Implemented (Phase 4 — connectors + credential vault)

```
GET    /connector-types                       # catalog of available connector types
GET    /connectors                 POST /connectors          # install (secrets in, never out)
GET    /connectors/{id}            PATCH /connectors/{id}    DELETE /connectors/{id}
GET    /connectors/{id}/tools
POST   /connectors/{id}/test                  # run the connector's connectivity check
```

Connector management requires `connectors:manage`; listing/tool-discovery require
`read`. Secrets are accepted only on write, stored with envelope encryption, and
**never returned** by any endpoint. Installed connectors contribute their tools to
the agent loop (e.g. `slack.post_message`); v1 ships HTTP, Slack, and Email.

## Implemented (Phase 5 — approvals inbox)

```
GET    /approvals[?status=pending]            # the approval inbox
GET    /approvals/{id}
POST   /approvals/{id}/approve                # resume the run and execute the action
POST   /approvals/{id}/reject                 # resume the run so the agent can replan
```

Reading approvals requires `read`; deciding requires `approvals:decide`
(Owner/Admin/Operator). When an agent proposes a sensitive action the policy
engine returns `require_approval`: the run is suspended (`waiting_approval`) and an
approval is created capturing the exact tool and arguments. Approving executes the
action and resumes; rejecting resumes so the agent can choose differently. Expired
or already-decided approvals return `409`. Workflow approval/tool-node pauses use
the same inbox.

## Implemented (Phase 6 — workflows + triggers)

```
GET    /workflows              POST /workflows        # POST returns webhook_url + secret once
GET    /workflows/{id}         PATCH /workflows/{id}  DELETE /workflows/{id}
POST   /workflows/{id}/run                            # manual trigger

POST   /hooks/{webhook_token}                          # signed inbound webhook (public, HMAC)
```

A workflow is a graph of nodes (`trigger` / `agent` / `tool` / `condition` /
`transform` / `approval` / `delay`) and edges with optional `when` branches, using
sandboxed `{{ }}` templating over prior node outputs. Managing workflows requires
`build:write`; running requires `runs:execute`. Triggers: **manual** (the run
endpoint), **webhook** (HMAC-signed `POST /hooks/{token}` — invalid signatures are
`401`), **schedule** (cron, via Celery beat), and internal **events**. Approval and
sensitive-tool nodes pause the run and resume through the approvals inbox; each node
is persisted as a `Step`, so runs are fully reconstructable.

All workspace-scoped endpoints derive the active workspace from the auth context
(JWT `ws` claim or the API key's workspace). RBAC is enforced per the Section 7.3
matrix.

## Auth

- **Bearer JWT**: `Authorization: Bearer <access_token>`.
- **API key**: `X-API-Key: lg_...`. Scope-gated, workspace-scoped.
