# Isis API Documentation

Isis provides three Hono-based REST API services for AI content generation:

1. **Generation API** (port 4001) -- Job submission, model management, and
   generation orchestration
2. **Workflow Registry** (port 3001) -- ComfyUI workflow and template management
   with versioning
3. **Output Registry** (port 3002) -- Output manifest storage, provenance
   tracking, and retention policies

All three services use consistent JSON error responses, CORS configuration, and
security headers.

### Structured Security Logs

All Isis services now emit structured security events for sensitive operations:

- Event name: `security.sensitive_operation`
- Key fields: `outcome`, `method`, `path`, `status`, `durationMs`, `actorId`,
  `authScheme`, `projectScope`, `requestId`, and `error` (when present)
- Outcome semantics: `allowed` (2xx/3xx), `denied` (4xx), `error` (5xx)

Sensitive-route coverage:

- Generation API: non-`GET` workflow/model mutations, provider/admin controls,
  dead-letter operations, and RunPod webhook callbacks.
- Workflow Registry: non-`GET` workflow/template mutations and workflow audit
  log reads.
- Output Registry: non-`GET` output mutations, provenance and retention policy
  operations, and sensitive reads such as output stats and lineage/provenance
  lookups.

---

## Generation API (Port 4001)

The primary API for submitting AI generation jobs and managing models. Built
with Hono, it includes JWT authentication, rate limiting, Zod request
validation, and secure headers.

### Base URL

```
http://localhost:4001
```

### Authentication

The Generation API supports two authentication schemes on all `/api/*` routes:

**1. JWT Bearer Token (preferred)**

```
Authorization: Bearer <jwt-token>
```

- Algorithm: HS256 (HMAC-SHA256)
- Required claims: `sub` (user ID)
- Optional claims: `email`, `roles[]`, `iss`, `aud`, `exp`, `iat`,
  `organizationId`
- Clock tolerance: 60 seconds for `exp`/`nbf` validation
- **`JWT_SECRET` is REQUIRED in production** -- service will refuse to start
  without it

**2. API Key**

```
X-API-Key: <key-id>:<secret>
```

- Returns `keyId`, `ownerId`, and `permissions[]` from the key validator
- Permissions are checked per-endpoint as needed

**Authentication behavior:**

| Environment | No credentials      | Invalid JWT | No JWT_SECRET configured                    |
| ----------- | ------------------- | ----------- | ------------------------------------------- |
| Development | Allowed (anonymous) | 401         | Warning logged, JWT auth rejects all tokens |
| Production  | 401 Unauthorized    | 401         | **Fatal: service will not start**           |

**Skipped routes:** `/health` and `/ready` bypass authentication entirely.

### Rate Limiting

All `/api/*` routes are rate-limited:

- **Default:** 100 requests per 60-second window
- **Key:** `X-API-Key` header, then `X-Forwarded-For` header, then `anonymous`

**Rate limit headers (on every response):**

| Header                  | Description                           |
| ----------------------- | ------------------------------------- |
| `X-RateLimit-Limit`     | Maximum requests per window           |
| `X-RateLimit-Remaining` | Remaining requests in current window  |
| `X-RateLimit-Reset`     | ISO 8601 timestamp when window resets |

**429 response:**

```json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "retryAfter": 45
  }
}
```

### Abuse Controls for Expensive Endpoints

Beyond baseline request rate limiting, generation endpoints with direct compute
cost enforce weighted abuse-control budgets:

- Protected endpoints: `POST /api/v1/jobs`, `POST /api/v1/jobs/batch`,
  `POST /api/v1/jobs/:id/retry`
- Budgets are evaluated per actor and per project across burst and sustained
  windows.
- Request cost is weighted by generation type and request complexity (`steps`,
  resolution, priority), with per-request unit caps.

Response headers:

- `X-AbuseControl-Enabled`, `X-AbuseControl-Operation`, `X-AbuseControl-Units`
- `X-AbuseControl-actor-burst-limit`, `...-remaining`, `...-reset`
- `X-AbuseControl-actor-sustained-limit`, `...-remaining`, `...-reset`
- `X-AbuseControl-project-burst-limit`, `...-remaining`, `...-reset`
- `X-AbuseControl-project-sustained-limit`, `...-remaining`, `...-reset`

When blocked, APIs return `429` with `Retry-After` and error code
`ABUSE_CONTROL_LIMIT_EXCEEDED`.

### CORS

Allowed methods: `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS` Allowed headers:
`Content-Type`, `Authorization`, `X-API-Key`, `X-Isis-Project-Id`,
`X-Correlation-Id`, `X-Request-Id`, `X-Trace-Id`, `X-Span-Id`,
`X-Parent-Span-Id` Exposed headers: `X-RateLimit-Limit`,
`X-RateLimit-Remaining`, `X-RateLimit-Reset` Max age: 86400 seconds (24 hours)
Credentials: allowed

Origins are configured via the `CORS_ORIGINS` environment variable
(comma-separated). In development, localhost origins on ports 3000, 3001, 3002,
4200, and 5173 are allowed by default.

---

### Health Endpoints

#### `GET /health`

Lightweight liveness check.

**Response (200):**

```json
{
  "status": "ok",
  "service": "@isis/generation-api",
  "version": "0.1.0",
  "timestamp": "2026-02-14T12:00:00.000Z"
}
```

#### `GET /ready`

Readiness check including database and service dependencies.

**Response (200 or 503):**

```json
{
  "ready": true,
  "criticalDependencies": {
    "jobsDatabase": true,
    "modelsDatabase": true,
    "queue": true,
    "storage": true,
    "provider": true
  },
  "checks": {
    "jobsDatabase": "ok",
    "jobsDatabaseLatencyMs": 2,
    "jobsDatabaseError": null,
    "modelsDatabase": "ok",
    "modelsDatabaseLatencyMs": 1,
    "modelsDatabaseError": null,
    "queue": "ok",
    "queueName": "isis:jobs:submit",
    "queueCheckedAt": "2026-02-22T12:00:00.000Z",
    "queueRedis": "ok",
    "queueLiveness": "ok",
    "storage": "ok",
    "storageProvider": "s3",
    "storageProbeType": "read_write",
    "provider": "ok",
    "providerPrimary": "runpod",
    "providerStatuses": []
  }
}
```

Readiness alerting is emitted via structured logs when critical dependencies are
degraded:

- `READINESS_ALERTS_ENABLED` (default `true`)
- `READINESS_ALERT_FAILURE_THRESHOLD` (default `2` consecutive failed checks)
- `READINESS_ALERT_REMINDER_INTERVAL_MS` (default `300000`)

---

### Job Endpoints

All job endpoints are mounted at `/api/v1/jobs`.

#### `POST /api/v1/jobs` -- Submit a new job

**Auth required:** Yes

**Request body:**

```json
{
  "type": "text-to-image",
  "prompt": "A serene mountain landscape at sunset",
  "negativePrompt": "blurry, low quality",
  "inputUrl": "https://example.com/reference.png",
  "model": "stable-diffusion-xl",
  "parameters": {
    "width": 1024,
    "height": 1024,
    "steps": 30,
    "guidanceScale": 7.5,
    "seed": 42,
    "sampler": "euler_a"
  },
  "priority": "normal",
  "callbackUrl": "https://myapp.com/webhook/job-complete",
  "idempotencyKey": "req_abc123",
  "metadata": { "projectId": "proj_123" }
}
```

| Field            | Type   | Required | Description                                                                           |
| ---------------- | ------ | -------- | ------------------------------------------------------------------------------------- |
| `type`           | enum   | Yes      | Generation type (see table below)                                                     |
| `prompt`         | string | No       | Text prompt (max 2000 chars)                                                          |
| `negativePrompt` | string | No       | Negative prompt (max 1000 chars)                                                      |
| `inputUrl`       | string | No       | URL to input media (for img2img, vid2vid, etc.)                                       |
| `model`          | string | No       | Model identifier                                                                      |
| `parameters`     | object | No       | Generation parameters (see below)                                                     |
| `priority`       | enum   | No       | `low`, `normal` (default), `high`, `urgent`                                           |
| `callbackUrl`    | string | No       | Webhook URL for completion notification                                               |
| `idempotencyKey` | string | No       | Dedupe key. Reusing the same key returns the original job instead of enqueueing again |
| `metadata`       | object | No       | Arbitrary metadata attached to the job                                                |

**Generation types:**

| Type               | Description                            |
| ------------------ | -------------------------------------- |
| `text-to-image`    | Generate images from text prompts      |
| `image-to-image`   | Transform images with text guidance    |
| `text-to-video`    | Generate video from text               |
| `image-to-video`   | Animate a still image                  |
| `text-to-3d`       | Generate 3D models from text           |
| `image-to-3d`      | Generate 3D models from images         |
| `text-to-audio`    | Generate audio/sound effects from text |
| `voice-synthesis`  | Text-to-speech synthesis               |
| `music-generation` | Generate music from text prompts       |
| `upscaling`        | Upscale images/video                   |
| `inpainting`       | Fill masked regions in images          |

**Parameters:**

| Parameter       | Type   | Range   | Description                     |
| --------------- | ------ | ------- | ------------------------------- |
| `width`         | int    | 64-4096 | Output width in pixels          |
| `height`        | int    | 64-4096 | Output height in pixels         |
| `steps`         | int    | 1-150   | Diffusion steps                 |
| `guidanceScale` | number | 0-30    | Classifier-free guidance scale  |
| `seed`          | int    | any     | Random seed for reproducibility |
| `sampler`       | string | -       | Sampling algorithm              |

Additional parameters are accepted via `passthrough()`.

**Response (201):**

```json
{
  "jobId": "job_abc123",
  "status": "queued",
  "queuePosition": 3,
  "estimatedWaitTime": 45,
  "statusUrl": "http://localhost:4001/api/v1/jobs/job_abc123/status"
}
```

`status` is normally `queued`. It can be `pending` when the transactional outbox
accepted the job but immediate queue dispatch is deferred to the relay loop. It
can be `failed` when outbox dispatch exhausts the configured retry cap during
submit-time dispatch.

After enqueue, API-side lifecycle transitions are driven by BullMQ worker
ACK/NACK outcomes (`active`/`progress`/`completed`/`failed`) with terminal-state
guards so late queue events cannot overwrite `completed`/`failed`/`cancelled`.

#### `GET /api/v1/jobs` -- List jobs

**Query parameters:**

| Parameter   | Type     | Default     | Description                                   |
| ----------- | -------- | ----------- | --------------------------------------------- |
| `status`    | string[] | all         | Filter by status(es)                          |
| `type`      | string[] | all         | Filter by generation type(s)                  |
| `page`      | int      | 1           | Page number (1-based)                         |
| `limit`     | int      | 20          | Items per page (1-100)                        |
| `sortBy`    | enum     | `createdAt` | Sort field: `createdAt`, `status`, `priority` |
| `sortOrder` | enum     | `desc`      | Sort direction: `asc`, `desc`                 |

**Response (200):**

```json
{
  "items": [ { "id": "...", "type": "text-to-image", "status": "completed", ... } ],
  "total": 42,
  "page": 1,
  "limit": 20,
  "totalPages": 3
}
```

#### `GET /api/v1/jobs/stats` -- Get queue statistics

**Response (200):** Queue statistics including:

- Status totals (`totalJobs`, `byStatus`, `byType`)
- Throughput and processing (`avgProcessingTime`, `completedLastHour`,
  `failedLastHour`)
- Operational health:
  - `queueDepth` (`pending + queued + running`)
  - `stuckJobs` (`total`, `queued`, `running`, `thresholdMinutes`,
    `oldestAgeSeconds`)
  - `executionRetries` (`total`, `lastHour`, `byStatus`)
  - `deadLetterQueueSize`

#### `GET /api/v1/jobs/admin/queue/health` -- Get queue health (admin)

Returns live BullMQ queue health from Redis (`waiting`, `active`, `delayed`,
`failed`).

Access guard:

- Bearer auth must include role `admin`, `ops`, or `sre`.
- API key auth must include permission `jobs:queue:admin`.

#### `POST /api/v1/jobs/admin/queue/drain` -- Drain queue (admin)

Drains waiting and delayed jobs from the BullMQ queue and returns before/after
counts.

Access guard:

- Bearer auth must include role `admin`, `ops`, or `sre`.
- API key auth must include permission `jobs:queue:admin`.

#### `POST /api/v1/jobs/admin/legacy-pending/recover` -- Recover legacy pending jobs (admin)

Backfills missing outbox entries for legacy jobs that are still `pending` and
were created before queue wiring was introduced. Invalid/unrecoverable records
are marked `failed` with a recovery error message.

**Request body (optional):**

```json
{
  "limit": 200,
  "minimumAgeMs": 300000,
  "dispatchOutbox": true
}
```

Access guard:

- Bearer auth must include role `admin`, `ops`, or `sre`.
- API key auth must include permission `jobs:queue:admin`.

#### `POST /api/v1/jobs/admin/workflow-ids/backfill` -- Backfill workflow IDs (admin)

Backfills missing canonical `metadata.workflowId` values on historical jobs
using deterministic source precedence (`metadata` aliases, output metadata,
input parameters, project defaults, then generation-type defaults).

**Request body (optional):**

```json
{
  "limit": 2000,
  "dryRun": false
}
```

Response fields include:

- `scanned`, `missingWorkflowIds`, `backfilled`, `unresolved`, `failed`
- `backfilledJobIds`, `unresolvedJobIds`, `failedJobIds`
- `sourceCounts` (counts by resolution source)
- `checkedAt`

Access guard:

- Bearer auth must include role `admin`, `ops`, or `sre`.
- API key auth must include permission `jobs:queue:admin`.

#### `POST /api/v1/jobs/admin/costs/backfill` -- Backfill cost data (admin)

Backfills missing cost metadata on historical terminal jobs (`completed`,
`failed`, `cancelled`) using deterministic source precedence:

1. Imported provider log records (`providerLogs`)
2. Existing explicit cost aliases in job/output metadata
3. Runtime-derived estimation from provider runtime fields and configured rates

**Request body (optional):**

```json
{
  "limit": 2000,
  "dryRun": false,
  "providerLogs": [
    {
      "jobId": "job_abc123",
      "provider": "runpod",
      "executionTimeMs": 3240,
      "estimatedCostUsd": 0.1824,
      "endpointId": "endpoint_xyz",
      "occurredAt": "2026-02-22T12:34:56.000Z"
    }
  ]
}
```

Response fields include:

- `scanned`, `missingCostData`, `backfilled`, `unresolved`, `failed`
- `providerLogsProcessed`, `providerLogsMatched`
- `backfilledJobIds`, `unresolvedJobIds`, `failedJobIds`
- `sourceCounts`, `providerCounts`
- `checkedAt`

Access guard:

- Bearer auth must include role `admin`, `ops`, or `sre`.
- API key auth must include permission `jobs:queue:admin`.

#### `POST /webhooks/runpod` -- RunPod provider callback (signed)

Accepts RunPod asynchronous callback events and requires an HMAC signature in
`X-RunPod-Signature`.

Security requirements:

- `RUNPOD_WEBHOOK_SECRET` must be configured.
- Signature must be `sha256(payload)` (hex), with optional `sha256=` prefix.

**Request body (minimum):**

```json
{
  "id": "runpod_job_123",
  "status": "COMPLETED"
}
```

#### `GET /api/v1/jobs/:id` -- Get job details

**Response (200):** Full job object including input parameters, output (if
complete), timing, and metadata.

**Response (404):**

```json
{
  "error": { "code": "JOB_NOT_FOUND", "message": "Job job_abc123 not found" }
}
```

#### `GET /api/v1/jobs/:id/status` -- Get job status (polling-optimized)

Lightweight endpoint optimized for frequent polling. Returns
`Cache-Control: private, max-age=1`.

**Response (200):** Minimal status object with `id`, `status`, `progress`, and
timing fields.

#### `GET /api/v1/jobs/:id/queue-position` -- Get queue-backed position snapshot

Returns queue position derived from BullMQ state when available (`waiting`,
`prioritized`, `delayed`, `active`). Falls back to database estimation when the
queue cannot provide a resolvable position for the job.

**Response (200):** Includes `source` (`queue` or `database`), `queueState`,
`queuePosition`, `estimatedWaitTime`, and `checkedAt`.

#### `POST /api/v1/jobs/:id/cancel` -- Cancel a job

**Request body (optional):**

```json
{ "reason": "No longer needed" }
```

**Response (200):** Updated job object with `cancelled` status.

For jobs in `queued` state, the API removes the queued BullMQ job before
persisting cancellation. If the queue job is already active, cancellation is
rejected with `JOB_CANCEL_FAILED`.

The cancellation reason is persisted in both `error` and
`metadata.cancellation.reason`.

#### `GET /api/v1/jobs/dead-letter` -- List dead-letter queue entries

Returns paginated outbox entries moved to DLQ after retry exhaustion.

**Query parameters:**

| Parameter | Type | Default | Description                |
| --------- | ---- | ------- | -------------------------- |
| `page`    | int  | `1`     | Page number (1-based)      |
| `limit`   | int  | `20`    | Items per page (max `100`) |

#### `POST /api/v1/jobs/dead-letter/:outboxId/replay` -- Replay a dead-letter entry

Moves a DLQ entry back to `pending` relay state and triggers immediate relay
processing.

**Request body (optional):**

```json
{ "reason": "Operator replay after Redis incident" }
```

#### `DELETE /api/v1/jobs/:id` -- Delete a job

**Response (200):**

```json
{ "success": true }
```

#### `GET /api/v1/jobs/:id/output` -- Get job output

Returns output files only if job status is `completed`.

**Response (200):**

```json
{
  "files": [
    {
      "url": "https://storage.example.com/outputs/img_001.png",
      "filename": "img_001.png",
      "mimeType": "image/png",
      "sizeBytes": 2048576,
      "width": 1024,
      "height": 1024
    }
  ],
  "previewUrl": "https://storage.example.com/previews/img_001_thumb.jpg",
  "seed": 42,
  "metadata": {}
}
```

**Response (400):**

```json
{
  "error": {
    "code": "JOB_NOT_COMPLETE",
    "message": "Job job_abc123 is not complete (status: running)"
  }
}
```

#### `GET /api/v1/jobs/:id/audio` -- Get job audio contracts

Returns normalized audio-specific parameter contracts and retrieval links for
audio artifacts.

**Response (200):**

```json
{
  "jobId": "job_audio_001",
  "status": "completed",
  "generationType": "music-generation",
  "isAudioGeneration": true,
  "parameters": {
    "audioConditioning": {
      "mode": "style-transfer",
      "providerCapabilityMode": "required",
      "referenceAudioUrl": "https://assets.example/reference.wav",
      "conditioningStrength": 0.72
    },
    "voiceConsistency": {
      "profileId": "narrator-v2",
      "consistencyStrength": 0.84
    }
  },
  "output": {
    "available": true,
    "audioPackage": {
      "mixdown": {
        "url": "https://storage.example.com/outputs/audio-master.wav"
      }
    }
  },
  "retrieval": {
    "self": "/api/v1/jobs/job_audio_001/audio",
    "output": "/api/v1/jobs/job_audio_001/output",
    "mixdownUrl": "https://storage.example.com/outputs/audio-master.wav"
  }
}
```

**Response (400):**

```json
{
  "error": {
    "code": "JOB_AUDIO_UNAVAILABLE",
    "message": "Job job_abc123 has no audio-specific parameters or output contracts"
  }
}
```

---

### Model Endpoints

All model endpoints are mounted at `/api/v1/models`.

#### `POST /api/v1/models` -- Register a new model

**Auth required:** Yes

**Request body:** Model metadata including name, type, architecture, file
format, etc.

**Response (201):** Created model object.

**Response (409):**

```json
{
  "error": {
    "code": "MODEL_ALREADY_EXISTS",
    "message": "Model with name X already exists"
  }
}
```

#### `GET /api/v1/models` -- List models

**Query parameters:** Filters for type, visibility, pagination.

**Response (200):** Paginated list of models.

#### `GET /api/v1/models/:id` -- Get model by ID

**Response (200):** Full model object.

#### `GET /api/v1/models/by-name/:name/:version` -- Get model by name and version

**Response (200):** Model matching the exact name and version.

#### `PUT /api/v1/models/:id` -- Update model metadata

**Auth required:** Yes (must be owner or organization admin)

**Response (200):** Updated model object.

**Response (403):**

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to update this model"
  }
}
```

#### `DELETE /api/v1/models/:id` -- Delete a model

**Auth required:** Yes (must be owner or organization admin)

**Response (200):** `{ "success": true }`

#### `GET /api/v1/models/:id/versions` -- List model versions

**Response (200):** Array of version objects for the model.

#### `POST /api/v1/models/:id/upload-url` -- Generate presigned upload URL

**Auth required:** Yes (must be owner or organization admin)

**Request body:**

```json
{
  "filename": "model_v2.safetensors",
  "contentType": "application/octet-stream",
  "sizeBytes": 4294967296
}
```

**Response (200):**

```json
{
  "uploadUrl": "https://storage.example.com/upload?...",
  "fields": { "key": "models/...", "Content-Type": "..." },
  "storagePath": "models/abc123/model_v2.safetensors",
  "expiresAt": "2026-02-14T13:00:00.000Z"
}
```

#### `POST /api/v1/models/:id/upload-complete` -- Complete model upload

**Auth required:** Yes (must be owner or organization admin)

**Request body:**

```json
{
  "storagePath": "models/abc123/model_v2.safetensors",
  "sizeBytes": 4294967296,
  "hash": {
    "algorithm": "sha256",
    "value": "abc123..."
  }
}
```

**Response (200):** Updated model object with upload status set to complete.

Upload policy enforcement:

- Allowed MIME types and maximum size are enforced both when issuing upload URLs
  and when finalizing uploads.
- `POST /upload-complete` verifies object size and hash against stored object
  content before persisting completion.
- `POST /upload-complete` runs malware scanning on uploaded model content and
  blocks completion when malware threats are detected.
- Abandoned upload placeholders (models with no completed hash/size) are cleaned
  by retention policy, with optional object storage deletion.

#### `GET /api/v1/models/:id/download-url` -- Generate presigned download URL

Public models: available to all authenticated users. Private models: requires
ownership or organization membership.

**Response (200):** Object with `downloadUrl` and expiration.

**Response (410):**

```json
{
  "error": {
    "code": "MODEL_INACTIVE",
    "message": "Model model_123 is not active"
  }
}
```

---

## Workflow Registry (Port 3001)

Manages ComfyUI workflow definitions with versioning, templates, and validation.

### Base URL

```
http://localhost:3001
```

### Authentication

The Workflow Registry does not currently enforce authentication (uses a default
demo owner ID). Production deployments should add authentication middleware.

### Health Endpoints

#### `GET /health`

**Response (200):**

```json
{
  "status": "ok",
  "service": "@isis/workflow-registry",
  "version": "0.1.0",
  "timestamp": "2026-02-14T12:00:00.000Z"
}
```

#### `GET /ready`

**Response (200):**

```json
{
  "ready": true,
  "checks": { "storage": "ok", "storageType": "in-memory" }
}
```

---

### Workflow Endpoints

All workflow endpoints are mounted at `/api/v1/workflows`.

### Canonical Workflow Schema Contract (v1.0.0)

Isis workflow validation is published from `@isis/workflows` as schema `1.0.0`
with compatibility range `^1.0.0`.

Compatibility rules enforced by the shared schema package:

- Required top-level fields: `schema_version`, `workflow_info`, `inputs`,
  `nodes`, `prompt_construction`, `output_spec`.
- Schema versioning: `schema_version` follows semver and current canonical value
  is `1.0.0`.
- Migration registry: legacy definitions missing `schema_version` are migrated
  through the shared schema migration registry to canonical `1.0.0` before
  compatibility checks.
- Canonical node format: `nodes` must be an object map keyed by node ID.
- Legacy array workflow shape (`nodes[]` + `links[]`) is accepted through a
  reversible adapter and normalized to canonical schema.
- Strict metadata contracts: additional keys in `workflow_info`, input
  definitions, and node definitions are rejected.
- Extensibility points: additional top-level lookup/config maps and additional
  `output_spec` fields are allowed.

Custom node contract reference:

- `docs/domains/isis/api/CUSTOM_NODE_CONTRACTS.md`

#### `POST /api/v1/workflows` -- Create a workflow

**Request body:** Workflow definition including name, description, category,
engine type, nodes, and connections.

Input hardening:

- Request payloads for workflow mutation/validation routes are capped at
  `2,097,152` bytes (`2 MB`) and return `413` when exceeded.
- Workflow `definition` payload is capped at `2,097,152` bytes after JSON
  serialization.
- String fields are sanitized by stripping disallowed control characters.

**Response (201):** Created workflow object with generated ID and version 1.0.0.

#### `GET /api/v1/workflows` -- List workflows

**Query parameters:** Filters for category, engine type, search text,
pagination.

**Response (200):** Paginated list of workflows.

#### `POST /api/v1/workflows/validate` -- Validate a workflow definition

**Request body:** Workflow definition to validate.

**Response (200):**

```json
{
  "valid": true,
  "errors": [],
  "warnings": ["Node 'KSampler' has default parameters"]
}
```

#### `GET /api/v1/workflows/:id` -- Get workflow by ID

**Response (200):** Full workflow object.

#### `PATCH /api/v1/workflows/:id` -- Update workflow

**Request body:** Partial workflow update fields.

**Response (200):** Updated workflow object.

#### `DELETE /api/v1/workflows/:id` -- Delete workflow

**Response (200):** `{ "success": true }`

#### `GET /api/v1/workflows/:id/versions` -- List workflow versions

**Response (200):**

```json
{ "versions": [ { "version": "1.0.0", "createdAt": "...", "status": "active" }, ... ] }
```

#### `POST /api/v1/workflows/:id/versions` -- Create a new version

**Request body:** Version metadata including version string, changelog, and
optionally updated definition.

**Response (201):** Created version object.

#### `GET /api/v1/workflows/:id/versions/:version` -- Get specific version

**Response (200):** Version object with full workflow definition at that
version.

#### `POST /api/v1/workflows/:id/versions/:version/deprecate` -- Deprecate a version

**Response (200):** `{ "success": true }`

#### `POST /api/v1/workflows/packs/export` -- Export workflow pack

**Request body:** Workflow IDs with export controls (`includeHistory`,
`includeDefinitions`).

**Response (200):** Workflow pack payload containing exported workflows,
optional version history, and missing-ID diagnostics.

#### `POST /api/v1/workflows/packs/import` -- Import workflow pack

**Request body:** Workflow pack payload plus import controls (`importHistory`,
`continueOnError`, optional visibility override).

**Response (201/200/400):** Import summary with per-item success/failure
details.

#### `POST /api/v1/workflows/preset-bundles/export` -- Export preset bundle

**Request body:** Workflow IDs with `includeEmpty` control.

**Response (200):** Preset bundle payload extracted from workflow definitions
(`preset_*` fields), with missing/skipped diagnostics.

#### `POST /api/v1/workflows/preset-bundles/import` -- Import preset bundle

**Request body:** Workflow-targeted preset payload items.

**Response (201/200/400):** Import summary; successful imports create
incremented workflow versions with merged preset payloads.

---

### Template Endpoints

All template endpoints are mounted at `/api/v1/templates`.

#### `GET /api/v1/templates` -- List templates

**Query parameters:** Filters for category, engine type, search text,
pagination.

**Response (200):** Paginated list of templates.

#### `GET /api/v1/templates/:id` -- Get template by ID

**Response (200):** Full template object including parameter definitions and
defaults.

#### `POST /api/v1/templates/:id/create` -- Create workflow from template

**Request body:**

```json
{
  "templateId": "tmpl_abc123",
  "name": "My Custom Workflow",
  "parameters": {
    "width": 1024,
    "height": 1024,
    "model": "sdxl-base"
  }
}
```

Note: `templateId` in body must match the URL parameter.

**Response (201):** Created workflow object derived from the template.

---

## Output Registry (Port 3002)

Manages generated output manifests, provenance tracking, lineage graphs, and
retention policies.

### Base URL

```
http://localhost:3002
```

### Health Endpoints

#### `GET /health`

**Response (200):**

```json
{
  "status": "ok",
  "service": "@isis/output-registry",
  "version": "0.1.0",
  "timestamp": "2026-02-14T12:00:00.000Z"
}
```

#### `GET /ready`

**Response (200 or 503):**

```json
{
  "ready": true,
  "checks": {
    "database": "ok",
    "databaseLatencyMs": 2,
    "databaseError": null
  }
}
```

---

### Output Endpoints

All output endpoints are mounted at `/api/v1/outputs`.

#### `POST /api/v1/outputs` -- Register a new output

**Request body:** Output metadata including type, format, storage path, size,
checksums, and generation metadata.

**Response (201):** Created output object with generated ID.

#### `GET /api/v1/outputs` -- List outputs

**Query parameters:** Filters for type, format, date range, job ID, pagination.

**Response (200):** Paginated list of outputs.

#### `GET /api/v1/outputs/stats` -- Get storage statistics

**Response (200):** Aggregate stats including total outputs, total storage size,
counts by type/format.

#### `POST /api/v1/outputs/admin/provenance/backfill` -- Backfill provenance (admin)

Backfills missing provenance records for historical completed outputs
(`available`, `archived`, `expired`) that do not have a valid linked provenance
row.

**Request body (optional):**

```json
{
  "limit": 2000,
  "dryRun": false
}
```

Response fields include:

- `scanned`, `missingProvenance`, `backfilled`, `unresolved`, `failed`
- `backfilledOutputIds`, `unresolvedOutputIds`, `failedOutputIds`
- `sourceCounts`
- `checkedAt`

Access guard:

- Bearer auth must include role `admin`, `ops`, or `sre`.
- API key auth must include permission `outputs:admin`.

#### `GET /api/v1/outputs/:id` -- Get output by ID

**Response (200):** Full output object.

#### `PATCH /api/v1/outputs/:id` -- Update output

**Request body:** Partial output update fields (e.g., tags, metadata).

**Response (200):** Updated output object.

#### `DELETE /api/v1/outputs/:id` -- Delete output (soft delete)

**Response (200):** `{ "success": true }`

#### `GET /api/v1/outputs/:id/provenance` -- Get provenance

Returns the provenance record for an output, including source inputs, model
used, parameters, timestamps, and the generating user/service.

**Response (200):** Provenance object.

#### `POST /api/v1/outputs/:id/provenance` -- Register provenance

**Request body:**

```json
{
  "outputId": "out_abc123",
  "jobId": "job_xyz789",
  "model": "stable-diffusion-xl",
  "modelVersion": "1.0",
  "inputs": [{ "type": "prompt", "value": "A mountain landscape" }],
  "parameters": { "steps": 30, "guidanceScale": 7.5 },
  "generatedBy": "user_123"
}
```

Note: `outputId` in body must match the URL parameter.

**Response (201):** Created provenance object.

#### `GET /api/v1/outputs/:id/lineage` -- Get lineage graph

Returns the lineage/dependency graph showing how the output was derived from
inputs and intermediate outputs.

**Query parameters:**

| Parameter   | Type | Default | Description                         |
| ----------- | ---- | ------- | ----------------------------------- |
| `depth`     | int  | 3       | Maximum traversal depth             |
| `direction` | enum | `both`  | `upstream`, `downstream`, or `both` |

**Response (200):** Lineage graph with nodes (outputs) and edges (derivation
relationships).

#### `POST /api/v1/outputs/lineage` -- Add a lineage edge

**Request body:**

```json
{
  "sourceId": "out_source123",
  "targetId": "out_derived456",
  "relationship": "derived_from",
  "metadata": { "transformation": "upscale" }
}
```

**Response (201):** Created lineage edge.

---

### Retention Policy Endpoints

All policy endpoints are mounted at `/api/v1/policies`.

#### `GET /api/v1/policies` -- List retention policies

**Response (200):**

```json
{
  "policies": [
    {
      "name": "default",
      "retentionDays": 30,
      "appliesTo": { "types": ["image"], "minSize": 0 },
      "action": "delete"
    }
  ]
}
```

#### `GET /api/v1/policies/:name` -- Get retention policy by name

**Response (200):** Policy object.

#### `POST /api/v1/policies` -- Create or update retention policy

**Request body:**

```json
{
  "name": "large-files-cleanup",
  "retentionDays": 7,
  "appliesTo": { "minSize": 1073741824 },
  "action": "archive"
}
```

**Response (201):** Created/updated policy object.

#### `DELETE /api/v1/policies/:name` -- Delete retention policy

**Response (200):** `{ "success": true }`

#### `POST /api/v1/policies/apply` -- Apply retention policies

Triggers immediate application of all configured retention policies.

**Response (200):**

```json
{
  "success": true,
  "deleted": 15,
  "archived": 3,
  "totalBytesReclaimed": 5368709120
}
```

---

## Error Response Format

All three services use a consistent error response format:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description"
  }
}
```

### Common Error Codes

| Code                             | HTTP Status | Description                                   |
| -------------------------------- | ----------- | --------------------------------------------- |
| `NOT_FOUND`                      | 404         | Route not found                               |
| `INTERNAL_ERROR`                 | 500         | Unhandled server error                        |
| `RATE_LIMIT_EXCEEDED`            | 429         | Rate limit exceeded                           |
| `JOB_NOT_FOUND`                  | 404         | Job ID not found                              |
| `JOB_NOT_COMPLETE`               | 400         | Job not yet completed (for output retrieval)  |
| `JOB_SUBMIT_FAILED`              | 500         | Failed to submit job                          |
| `JOB_CANCEL_FAILED`              | 500         | Failed to cancel job                          |
| `DEAD_LETTER_NOT_FOUND`          | 404         | Dead-letter outbox entry not found            |
| `DEAD_LETTER_LIST_FAILED`        | 500         | Failed to list dead-letter entries            |
| `DEAD_LETTER_REPLAY_FAILED`      | 500         | Failed to replay dead-letter entry            |
| `LEGACY_PENDING_RECOVERY_FAILED` | 500         | Failed to recover legacy pending jobs         |
| `WORKFLOW_ID_BACKFILL_FAILED`    | 500         | Failed to backfill missing workflow IDs       |
| `COST_BACKFILL_FAILED`           | 500         | Failed to backfill missing historical costs   |
| `MODEL_NOT_FOUND`                | 404         | Model ID not found                            |
| `MODEL_ALREADY_EXISTS`           | 409         | Model with same name already registered       |
| `MODEL_INACTIVE`                 | 410         | Model is no longer active                     |
| `FORBIDDEN`                      | 403         | Insufficient permissions                      |
| `WORKFLOW_NOT_FOUND`             | 404         | Workflow ID not found                         |
| `WORKFLOW_CREATE_FAILED`         | 500         | Failed to create workflow                     |
| `VERSION_NOT_FOUND`              | 404         | Version not found                             |
| `TEMPLATE_NOT_FOUND`             | 404         | Template ID not found                         |
| `TEMPLATE_ID_MISMATCH`           | 400         | Template ID in body does not match URL        |
| `OUTPUT_NOT_FOUND`               | 404         | Output ID not found                           |
| `OUTPUT_ID_MISMATCH`             | 400         | Output ID in body does not match URL          |
| `PROVENANCE_NOT_FOUND`           | 404         | No provenance record for output               |
| `PROVENANCE_BACKFILL_FAILED`     | 500         | Failed to backfill missing provenance records |
| `POLICY_NOT_FOUND`               | 404         | Retention policy not found                    |

---

## Configuration

### Generation API

| Environment Variable                              | Default                        | Description                                                                         |
| ------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------- |
| `PORT`                                            | `4001`                         | HTTP server port                                                                    |
| `NODE_ENV`                                        | -                              | Environment (`development`/`production`)                                            |
| `JWT_SECRET`                                      | -                              | **Required in production.** HMAC secret for JWT verification                        |
| `JWT_ISSUER`                                      | `oshun`                        | Expected JWT issuer                                                                 |
| `JWT_AUDIENCE`                                    | `oshun-generation-api`         | Expected JWT audience                                                               |
| `CORS_ORIGINS`                                    | localhost defaults in dev      | Comma-separated allowed CORS origins                                                |
| `ISIS_QUEUE_NAME`                                 | `isis:jobs:submit` (dev)       | **Required in production.** BullMQ queue name for generation submit jobs            |
| `ISIS_QUEUE_REDIS_URL`                            | -                              | **Required in production unless `REDIS_URL` is set.** Redis URL for queue producer  |
| `REDIS_URL`                                       | `redis://localhost:6379` (dev) | Fallback Redis URL used by queue producer when `ISIS_QUEUE_REDIS_URL` is unset      |
| `ISIS_QUEUE_PRODUCER_ENABLED`                     | `true`                         | Feature flag to enable/disable outbox->queue dispatch for controlled rollout        |
| `ISIS_QUEUE_PRODUCER_CANARY_ENABLED`              | `false`                        | Enable canary queue dispatch while global queue producer is disabled                |
| `ISIS_QUEUE_PRODUCER_CANARY_PERCENTAGE`           | `0`                            | Percentage of canary-eligible submits routed to queue dispatch (`0-100`)            |
| `ISIS_QUEUE_PRODUCER_CANARY_PROJECT_IDS`          | -                              | Optional comma-separated project allowlist for queue canary rollout                 |
| `ISIS_QUEUE_LIFECYCLE_EVENTS_ENABLED`             | `true`                         | Enable/disable queue event listener that synchronizes worker ACK/NACK to job status |
| `ISIS_OUTBOX_POLL_MS`                             | `2000`                         | Poll interval in milliseconds for outbox relay retries                              |
| `ISIS_OUTBOX_BATCH_SIZE`                          | `20`                           | Max outbox records claimed and dispatched per relay cycle                           |
| `ISIS_OUTBOX_MAX_ATTEMPTS`                        | `5`                            | Max outbox dispatch attempts before terminal failure                                |
| `ISIS_OUTBOX_RETRY_BASE_MS`                       | `2000`                         | Base retry delay (ms) for outbox dispatch exponential backoff                       |
| `ISIS_OUTBOX_RETRY_MAX_MS`                        | `30000`                        | Max retry delay (ms) cap for outbox dispatch exponential backoff                    |
| `ISIS_OUTBOX_DLQ_RETENTION_DAYS`                  | `14`                           | Retention period in days before dead-letter entries are pruned                      |
| `ISIS_OUTBOX_DLQ_PRUNE_INTERVAL_MS`               | `60000`                        | Maintenance interval (ms) for dead-letter retention pruning                         |
| `ISIS_QUEUE_STUCK_JOB_THRESHOLD_MINUTES`          | `30`                           | Threshold minutes before queued/running jobs are counted as stuck                   |
| `ISIS_OPERATIONS_METRICS_ENABLED`                 | `true`                         | Enable periodic operational metrics snapshots in structured logs                    |
| `ISIS_OPERATIONS_METRICS_INTERVAL_MS`             | `60000`                        | Minimum interval (ms) between operational metrics snapshot emissions                |
| `ISIS_COST_RATE_RUNPOD_USD_PER_SECOND`            | `0`                            | Optional USD/sec fallback rate used for RunPod estimated cost telemetry             |
| `ISIS_COST_RATE_RUNCOMFY_USD_PER_SECOND`          | `0`                            | Optional USD/sec fallback rate used for RunComfy estimated cost telemetry           |
| `ISIS_COST_RATE_DEFAULT_USD_PER_SECOND`           | `0`                            | Optional fallback USD/sec rate used when provider-specific rate is unset            |
| `ISIS_RUNPOD_BUDGET_GUARDRAIL_ENABLED`            | `false`                        | Enable automatic RunPod spend guardrail enforcement on submit/batch/retry           |
| `ISIS_RUNPOD_BUDGET_SOFT_LIMIT_USD`               | `0`                            | Monthly estimated spend threshold that activates throttle mode                      |
| `ISIS_RUNPOD_BUDGET_HARD_LIMIT_USD`               | `0`                            | Monthly estimated spend threshold that blocks requests with `429`                   |
| `ISIS_RUNPOD_BUDGET_THROTTLE_UNITS_PER_WINDOW`    | `120`                          | Max weighted guardrail units allowed in each throttle window                        |
| `ISIS_RUNPOD_BUDGET_THROTTLE_WINDOW_SECONDS`      | `60`                           | Duration in seconds for guardrail throttle window                                   |
| `ISIS_RUNPOD_BUDGET_COST_CACHE_SECONDS`           | `60`                           | Cache TTL in seconds for RunPod cost lookups used by guardrail decisions            |
| `ISIS_RUNPOD_BUDGET_RETRY_AFTER_SECONDS`          | `60`                           | Retry hint in seconds returned when hard-limit guardrail blocks requests            |
| `ISIS_RUNPOD_BUDGET_FAIL_CLOSED`                  | `false`                        | If `true`, missing RunPod cost telemetry blocks requests instead of failing open    |
| `ISIS_LEGACY_PENDING_RECOVERY_ENABLED`            | `true`                         | Enable startup migration/cleanup pass for legacy `pending` jobs without outbox rows |
| `ISIS_LEGACY_PENDING_RECOVERY_BATCH_SIZE`         | `200`                          | Max legacy pending jobs scanned per recovery invocation                             |
| `ISIS_LEGACY_PENDING_RECOVERY_MIN_AGE_MS`         | `300000`                       | Minimum job age in milliseconds before a legacy `pending` job is eligible           |
| `ISIS_ABUSE_CONTROL_ENABLED`                      | `true`                         | Enable weighted abuse controls for expensive generation endpoints                   |
| `ISIS_ABUSE_ACTOR_BURST_UNITS`                    | `80`                           | Per-actor burst budget units                                                        |
| `ISIS_ABUSE_ACTOR_BURST_WINDOW_SECONDS`           | `60`                           | Burst window for actor budget                                                       |
| `ISIS_ABUSE_ACTOR_SUSTAINED_UNITS`                | `1200`                         | Per-actor sustained budget units                                                    |
| `ISIS_ABUSE_ACTOR_SUSTAINED_WINDOW_SECONDS`       | `3600`                         | Sustained window for actor budget                                                   |
| `ISIS_ABUSE_PROJECT_BURST_UNITS`                  | `240`                          | Per-project burst budget units                                                      |
| `ISIS_ABUSE_PROJECT_BURST_WINDOW_SECONDS`         | `60`                           | Burst window for project budget                                                     |
| `ISIS_ABUSE_PROJECT_SUSTAINED_UNITS`              | `3600`                         | Per-project sustained budget units                                                  |
| `ISIS_ABUSE_PROJECT_SUSTAINED_WINDOW_SECONDS`     | `3600`                         | Sustained window for project budget                                                 |
| `ISIS_ABUSE_MAX_UNITS_PER_REQUEST`                | `400`                          | Maximum unit cost charged for one request                                           |
| `ISIS_ABUSE_RETRY_UNITS`                          | `3`                            | Unit cost charged for `POST /api/v1/jobs/:id/retry`                                 |
| `ISIS_MODEL_SIGNED_URL_EXPIRY_SECONDS`            | `3600`                         | Expiration in seconds for model upload/download signed URLs                         |
| `ISIS_MODEL_UPLOAD_MAX_SIZE_BYTES`                | `5368709120`                   | Maximum allowed model upload size (bytes)                                           |
| `ISIS_MODEL_UPLOAD_ALLOWED_MIME_TYPES`            | built-in allowlist             | Comma-separated MIME types accepted for model uploads                               |
| `ISIS_MODEL_MALWARE_SCAN_ENABLED`                 | `true`                         | Enable malware scan hook for `POST /models/:id/upload-complete`                     |
| `ISIS_MODEL_MALWARE_SCAN_ENGINE`                  | `builtin`                      | Malware scanner engine (`builtin` or `clamav`)                                      |
| `ISIS_MODEL_MALWARE_SCAN_FAIL_CLOSED`             | `true`                         | If `true`, scanner failures block upload completion                                 |
| `ISIS_MODEL_MALWARE_SCAN_CLAMAV_HOST`             | `localhost`                    | ClamAV host when `ISIS_MODEL_MALWARE_SCAN_ENGINE=clamav`                            |
| `ISIS_MODEL_MALWARE_SCAN_CLAMAV_PORT`             | `3310`                         | ClamAV port when `ISIS_MODEL_MALWARE_SCAN_ENGINE=clamav`                            |
| `ISIS_MODEL_MALWARE_SCAN_CLAMAV_TIMEOUT_MS`       | `30000`                        | ClamAV scan timeout in milliseconds                                                 |
| `ISIS_MODEL_ABANDONED_UPLOAD_RETENTION_HOURS`     | `24`                           | Age threshold (hours) for deleting stale uncompleted model uploads                  |
| `ISIS_MODEL_ABANDONED_UPLOAD_CLEANUP_INTERVAL_MS` | `600000`                       | Interval for abandoned-upload cleanup loop                                          |
| `ISIS_MODEL_ABANDONED_UPLOAD_CLEANUP_BATCH_SIZE`  | `100`                          | Max stale upload records cleaned per interval                                       |
| `ISIS_MODEL_ABANDONED_UPLOAD_DELETE_STORAGE`      | `true`                         | If `true`, cleanup also deletes orphaned objects from model storage                 |

### Workflow Registry

| Environment Variable | Default                   | Description                          |
| -------------------- | ------------------------- | ------------------------------------ |
| `PORT`               | `3001`                    | HTTP server port                     |
| `CORS_ORIGINS`       | localhost defaults in dev | Comma-separated allowed CORS origins |

### Output Registry

| Environment Variable | Default                   | Description                          |
| -------------------- | ------------------------- | ------------------------------------ |
| `PORT`               | `3002`                    | HTTP server port                     |
| `CORS_ORIGINS`       | localhost defaults in dev | Comma-separated allowed CORS origins |

---

## Load Testing

Isis generation queue load tests are implemented with k6 under:
`testing/performance/k6/isis`.

Run commands:

```bash
# Enqueue throughput test
pnpm exec nx run @isis/generation-api:load-test

# Worker consumption test
pnpm exec nx run @isis/generation-api:load-test --configuration=worker

# Run both sequentially
pnpm exec nx run @isis/generation-api:load-test --configuration=combined
```

Worker-consumption tests require live worker processes so seeded jobs can
advance through `queued -> running -> completed|failed`.

---

## Related Documentation

- [Isis Domain Overview](../README.md) -- Full app and library inventory
- [Isis Architecture](../architecture.md) -- System design and data flow
- [External Integration Examples](./external-integration-examples.md) -- Typed
  game-engine and DCC automation SDK examples
- [ComfyUI Integration](../../../integrations/comfyui/README.md) -- ComfyUI
  workflow authoring
- [API Authentication](../../../api/authentication.md) -- Cross-domain auth
  patterns
