Agent Tool API

# NOVA//INK Agent Tool API

Base path: `/api/agent`

Authentication uses `Authorization: Bearer $NOVA_AGENT_TOKEN`. Token exists only in server runtime environment. Requests use `Content-Type: application/json`. Maximum body size is 1 MiB. A batch accepts at most 25 operations.

## Error shape

```json
{"ok":false,"error":{"code":"INVALID_INPUT","message":"Human-readable message"}}
```

## Project lifecycle

### `POST /api/agent/create_project`

```json
{"name":"Astra Nyx","characterName":"Astra Nyx","workflow":"VTuber Half Body","width":1200,"height":1200,"privacy":"public"}
```

### `POST /api/agent/set_character_brief`

```json
{"projectId":"prj_...","brief":{"archetype":"Cosmic navigator","personality":"Calm and confident"}}
```

### `POST /api/agent/create_session`

```json
{"projectId":"prj_...","actorType":"agent"}
```

### `POST /api/agent/finish_session`

```json
{"sessionId":"ses_...","status":"completed"}
```

## Layer tools

Endpoints: `create_layer`, `rename_layer`, `reorder_layer`, `select_layer`, `set_layer_visibility`, `set_layer_opacity`, `set_blend_mode`.

```json
{"projectId":"prj_...","name":"02_Lineart","opacity":1,"blendMode":"normal"}
```

## Drawing tools

Endpoints: `draw_stroke`, `draw_line`, `draw_curve`, `draw_shape`, `fill_region`, `erase_stroke`, `transform_selection`, `add_text`.

Every drawing request accepts a canonical operation. Retries must reuse the same `operationId`.

```json
{
  "operationId":"a22ae89c-c4da-48d2-8c87-766e255f79fd",
  "sessionId":"ses_...",
  "projectId":"prj_...",
  "actorId":"nova-agent",
  "actorType":"agent",
  "sequence":1,
  "timestamp":"2026-08-15T10:00:00.000Z",
  "tool":"ink",
  "layerId":"lay_...",
  "brush":{"size":8,"opacity":1,"flow":1,"hardness":1,"spacing":0.1,"smoothing":0.5},
  "color":"#7C5CFFFF",
  "geometry":{"points":[{"x":100,"y":200,"pressure":0.5},{"x":120,"y":220,"pressure":0.8}]}
}
```

Successful response:

```json
{"ok":true,"operationId":"...","revision":42,"status":"confirmed","duplicate":false}
```

## Batch

### `POST /api/agent/batch`

```json
{"operations":[{"operationId":"...","sessionId":"...","projectId":"...","sequence":1,"tool":"line","layerId":"...","color":"#EEF2FFFF","geometry":{"x1":10,"y1":10,"x2":200,"y2":200}}]}
```

Operations commit serially and broadcast individually. A failed item stops later items. Confirmed earlier items remain idempotently retryable.

## State and progress

Endpoints: `get_canvas_state`, `get_layer_state`, `get_session_state`, `create_checkpoint`, `set_stage`, `set_progress`, `undo`, `redo`, `export_project`.

```json
{"sessionId":"ses_...","afterRevision":0}
```

`get_canvas_state` returns project metadata, layers, current session, and canonical operations. `export_project` returns URLs for Project JSON, replay JSON, and layered archive ZIP.