Eve library

Isis API Documentation

Guide

Revision 1

On this page

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#

text
http://localhost:4001

Authentication#

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

1. JWT Bearer Token (preferred)

text
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

text
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#

text
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#

text
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.