Reference

Server API

The CLI is a thin shell over the local server — most /api/* routes have a CLI wrapper. Agent Mode is web-UI only; prompt builder is also available through ima2 prompt build. This page maps the endpoint groups; for full request and response shapes, see API.md.

Base URL

All endpoints are served locally. The default base is http://localhost:3333; the actual bound port is advertised in ~/.ima2/server.json (prefer backend.url).

Generation

Endpoint	Purpose
`POST /api/generate`	Text-to-image and reference-guided root generation.
`POST /api/edit`	Image edit / image-to-image generation.
`POST /api/generate/multimode` (SSE)	Multimode batch.
`POST /api/node/generate` (SSE)	Node-mode generation and child edits.
`GET /api/node/:nodeId`	Fetch stored node metadata and asset URL.
`POST /api/video/generate` (SSE)	Video generation via Grok (T2V/I2V/Ref2V).

POST /api/generate — request body

{
  "prompt": "a shiba in space",
  "quality": "medium",
  "size": "1024x1024",
  "format": "png",
  "moderation": "low",
  "provider": "oauth",
  "model": "gpt-5.4",
  "references": [],
  "requestId": "optional-client-id"
}

Quality: low, medium, high. Moderation: auto, low. Provider: auto, oauth, api, grok. Recommended OpenAI model gpt-5.4; app default gpt-5.4-mini. Grok models are grok-imagine-image and grok-imagine-image-quality. SSE routes emit phase, partial, done, and error when the client sends Accept: text/event-stream.

Video generation. POST /api/video/generate (SSE) generates videos via Grok. Models: grok-imagine-video, grok-imagine-video-1.5-preview. Modes: text-to-video, image-to-video, reference-to-video (2–7 refs). CLI: ima2 video.

History

Endpoint	Notes
`GET /api/history`	List generated assets; `?groupBy=session` groups by session title.
`DELETE /api/history/:filename`	Tombstone a generated asset.
`POST /api/history/:filename/restore`	Restore a recently deleted asset.

Sessions & graphs

Endpoint	Notes
`GET /api/sessions` · `POST /api/sessions`	List or create graph sessions.
`GET /api/sessions/:id`	Load a session and its graph.
`PATCH /api/sessions/:id` · `DELETE /api/sessions/:id`	Rename or delete a session.
`PUT /api/sessions/:id/graph`	Save a graph snapshot.

Optimistic concurrency. Graph saves require an If-Match header with the current version. A stale version returns GRAPH_VERSION_CONFLICT plus the current version — it only means you saved against a stale snapshot, not that another tab changed the graph.

Agent Mode & discovery

Agent Mode is a conversational image workspace (sessions, turns, and a durable per-session queue). These routes are always registered but have no CLI wrapper — drive Agent Mode from the web UI.

Endpoint	Purpose
`GET /api/capabilities`	Agent-facing discovery: supported models, valid values, limits, version (`ima2 capabilities`).
`GET · POST /api/agent/sessions`	List or create agent sessions.
`GET · PATCH · DELETE /api/agent/sessions/:id`	Load, update, or delete a session.
`POST /api/agent/sessions/:id/turns`	Run an agent turn; supports slash commands and `/question`.
`GET · POST /api/agent/sessions/:id/queue`	Inspect or enqueue durable queue work (`/api/agent/queue/:itemId/cancel` · `retry` manage items).
`POST /api/prompt-builder/chat`	Prompt-builder assistant (`ima2 prompt build`).

Health, storage & jobs

Endpoint	Notes
`GET /api/health`	Health check (`ima2 ping`).
`GET /api/providers`	Provider availability and runtime ports (`ima2 providers`).
`GET /api/oauth/status`	OAuth proxy status (`ima2 oauth status`).
`GET /api/grok/status`	Bundled progrok status and xAI model probe (`ima2 grok status`).
`GET /api/storage/status`	Storage inspection.
`POST /api/storage/open-generated-dir`	Open the generated directory in the OS file manager.
`GET /api/inflight` · `DELETE /api/inflight/:id`	List or force-remove in-flight jobs.

Common error codes

Code	Meaning
`API_KEY_REQUIRED`	API path requested without a configured key.
`INVALID_IMAGE_MODEL`	Model name is unknown or unsupported.
`IMAGE_MODEL_UNSUPPORTED`	Model exists but cannot use image generation.
`SAFETY_REFUSAL` · `MODERATION_REFUSED`	Upstream safety / moderation refusal.
`AUTH_CHATGPT_EXPIRED`	Codex/ChatGPT OAuth session expired.
`AUTH_API_KEY_INVALID`	API key is invalid, revoked, or out of quota.
`NETWORK_FAILED`	Network, proxy, VPN, or firewall failure.
`OAUTH_UNAVAILABLE`	Local OAuth proxy is not available.
`GRAPH_VERSION_CONFLICT`	Save made against a stale graph version.
`NODE_NOT_FOUND`	Node metadata was not found.
`GROK_REF_TOO_MANY`	Grok request included more than three total input images.
`GROK_MASK_UNSUPPORTED`	Grok edit was requested with a mask.
`INVALID_GROK_IMAGE_MODEL`	Grok request used an unsupported image model.
`GROK_RATE_LIMITED` · `GROK_AUTH_FAILED`	xAI rate-limit or auth failure through progrok.
`GROK_SEARCH_TIMEOUT` · `GROK_PLANNER_TIMEOUT` · `GROK_IMAGE_TIMEOUT`	One Grok phase exceeded its timeout budget.

The full endpoint → CLI mapping, reference-image error codes, and style-sheet routes are in API.md.

Configuration