Isis provides three Hono-based REST API services for AI content generation:
- Generation API (port 4001) -- Job submission, model management, and generation orchestration
- Workflow Registry (port 3001) -- ComfyUI workflow and template management with versioning
- 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, anderror(when present) - Outcome semantics:
allowed(2xx/3xx),denied(4xx),error(5xx)
Sensitive-route coverage:
- Generation API: non-
GETworkflow/model mutations, provider/admin controls, dead-letter operations, and RunPod webhook callbacks. - Workflow Registry: non-
GETworkflow/template mutations and workflow audit log reads. - Output Registry: non-
GEToutput 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/nbfvalidation JWT_SECRETis REQUIRED in production -- service will refuse to start without it
2. API Key
X-API-Key: <key-id>:<secret>
- Returns
keyId,ownerId, andpermissions[]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-Keyheader, thenX-Forwarded-Forheader, thenanonymous
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:
{
"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-UnitsX-AbuseControl-actor-burst-limit,...-remaining,...-resetX-AbuseControl-actor-sustained-limit,...-remaining,...-resetX-AbuseControl-project-burst-limit,...-remaining,...-resetX-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):
{
"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):
{
"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(defaulttrue)READINESS_ALERT_FAILURE_THRESHOLD(default2consecutive failed checks)READINESS_ALERT_REMINDER_INTERVAL_MS(default300000)
Job Endpoints#
All job endpoints are mounted at /api/v1/jobs.
POST /api/v1/jobs -- Submit a new job#
Auth required: Yes
Request body:
{
"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):
{
"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):
{
"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, orsre. - 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, orsre. - 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):
{
"limit": 200,
"minimumAgeMs": 300000,
"dispatchOutbox": true
}
Access guard:
- Bearer auth must include role
admin,ops, orsre. - 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):
{
"limit": 2000,
"dryRun": false
}
Response fields include:
scanned,missingWorkflowIds,backfilled,unresolved,failedbackfilledJobIds,unresolvedJobIds,failedJobIdssourceCounts(counts by resolution source)checkedAt
Access guard:
- Bearer auth must include role
admin,ops, orsre. - 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:
- Imported provider log records (
providerLogs) - Existing explicit cost aliases in job/output metadata
- Runtime-derived estimation from provider runtime fields and configured rates
Request body (optional):
{
"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,failedproviderLogsProcessed,providerLogsMatchedbackfilledJobIds,unresolvedJobIds,failedJobIdssourceCounts,providerCountscheckedAt
Access guard:
- Bearer auth must include role
admin,ops, orsre. - 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_SECRETmust be configured.- Signature must be
sha256(payload)(hex), with optionalsha256=prefix.
Request body (minimum):
{
"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):
{
"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):
{ "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):
{ "reason": "Operator replay after Redis incident" }
DELETE /api/v1/jobs/:id -- Delete a job#
Response (200):
{ "success": true }
GET /api/v1/jobs/:id/output -- Get job output#
Returns output files only if job status is completed.
Response (200):
{
"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):
{
"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):
{
"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):
{
"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):
{
"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):
{
"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:
{
"filename": "model_v2.safetensors",
"contentType": "application/octet-stream",
"sizeBytes": 4294967296
}
Response (200):
{
"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:
{
"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-completeverifies object size and hash against stored object content before persisting completion.POST /upload-completeruns 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):
{
"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):
{
"status": "ok",
"service": "@isis/workflow-registry",
"version": "0.1.0",
"timestamp": "2026-02-14T12:00:00.000Z"
}
GET /ready#
Response (200):
{
"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_versionfollows semver and current canonical value is1.0.0. - Migration registry: legacy definitions missing
schema_versionare migrated through the shared schema migration registry to canonical1.0.0before compatibility checks. - Canonical node format:
nodesmust 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_specfields 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,152bytes (2 MB) and return413when exceeded. - Workflow
definitionpayload is capped at2,097,152bytes 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):
{
"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):
{ "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:
{
"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):
{
"status": "ok",
"service": "@isis/output-registry",
"version": "0.1.0",
"timestamp": "2026-02-14T12:00:00.000Z"
}
GET /ready#
Response (200 or 503):
{
"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):
{
"limit": 2000,
"dryRun": false
}
Response fields include:
scanned,missingProvenance,backfilled,unresolved,failedbackfilledOutputIds,unresolvedOutputIds,failedOutputIdssourceCountscheckedAt
Access guard:
- Bearer auth must include role
admin,ops, orsre. - 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:
{
"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:
{
"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):
{
"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:
{
"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):
{
"success": true,
"deleted": 15,
"archived": 3,
"totalBytesReclaimed": 5368709120
}
Error Response Format#
All three services use a consistent error response format:
{
"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:
# 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 -- Full app and library inventory
- Isis Architecture -- System design and data flow
- External Integration Examples -- Typed game-engine and DCC automation SDK examples
- ComfyUI Integration -- ComfyUI workflow authoring
- API Authentication -- Cross-domain auth patterns