API Reference

API Reference

Complete REST API documentation for the SpaceHarbor control-plane.

See also: API Overview | API Authentication | API Endpoint Groups | API Error Handling | API Examples

Resource	Path
API Base	/api/v1/
Swagger UI	/api/docs
OpenAPI Spec	/openapi.json

API Access

Base URL

Environment	Base URL	Notes
Local dev	http://localhost:8080	Default, override with PORT env
Docker Compose	http://control-plane:8080	Internal service name
Production	https://your-domain/	Behind reverse proxy / load balancer

API Versioning

Routes are registered under two prefixes:

• /api/v1/... — Versioned (recommended for integrations)
• /... — Legacy (identical behavior, may be removed in future)

OpenAPI / Swagger

The API is fully documented via OpenAPI 3.0.3, generated dynamically from route schemas at runtime.

Endpoint	Purpose	Auth Required
GET /openapi.json	Machine-readable OpenAPI 3.0.3 spec (JSON)	No
GET /api/docs	Interactive Swagger UI with "Try it out"	No

Both endpoints are available in all environments (dev and production). They are explicitly exempt from IAM authentication.

# Download the OpenAPI spec
curl -s http://localhost:8080/openapi.json -o openapi.json

# Open Swagger UI in browser
open http://localhost:8080/api/docs

Note: A static snapshot of the spec is also committed at docs/openapi-snapshot.json in the repository.

Authentication & Authorization

SpaceHarbor supports four authentication strategies, configured via environment variables.

Security Schemes

Scheme	Type	Header / Method	Use Case
BearerAuth	HTTP Bearer (JWT)	Authorization: Bearer <jwt>	User sessions (web UI, CLI)
ApiKeyAuth	API Key	x-api-key: <key>	Service-to-service, worker automation
ServiceTokenAuth	API Key	x-service-token: <token>	Internal machine-to-machine
ScimTokenAuth	HTTP Bearer	Authorization: Bearer <scim-token>	Identity provider SCIM provisioning

Auth Behavior

• IAM disabled (default in dev): All requests pass through. Write operations may require x-api-key if SPACEHARBOR_API_KEY is set.
• IAM enabled (SPACEHARBOR_IAM_ENABLED=true): Every request must carry valid credentials. Unauthenticated requests receive 401.
• Shadow mode (SPACEHARBOR_IAM_SHADOW_MODE=true): RBAC decisions are logged but not enforced. Dev-only.

Public Endpoints (No Auth Required)

These endpoints bypass authentication even when IAM is enabled:

Endpoint	Purpose
GET /health	Liveness probe
GET /health/ready	Readiness probe
POST /auth/login	User login
POST /auth/refresh	Token refresh
GET /auth/token	Token refresh (GET variant)
GET /events/stream	SSE event stream
POST /device/code	Device authorization grant
POST /device/token	Device token exchange
GET /openapi.json	OpenAPI spec
GET /api/*	Swagger UI

Login Flow

# 1. Authenticate
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@spaceharbor.dev", "password": "Admin1234!dev"}'

# Response: { "accessToken": "eyJ...", "refreshToken": "abc123", "expiresIn": 3600 }

# 2. Use the access token
curl http://localhost:8080/api/v1/assets \
  -H "Authorization: Bearer eyJ..."

# 3. Refresh when expired
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refreshToken": "abc123"}'

Endpoint Groups

The API is organized into the following tag groups. All endpoints are documented in the OpenAPI spec at /openapi.json.

Assets (assets)

Core asset lifecycle operations.

Method	Path	Summary	Auth
GET	/api/v1/assets	List assets with filtering, search, pagination	BearerAuth
GET	/api/v1/assets/:id	Get asset detail	BearerAuth
GET	/api/v1/assets/:id/versions	Get asset version history	BearerAuth
GET	/api/v1/assets/:id/pipeline-status	Get pipeline processing status	BearerAuth
POST	/api/v1/assets/ingest	Ingest a new asset	ApiKeyAuth
POST	/api/v1/assets/upload-url	Generate pre-signed upload URL	BearerAuth
POST	/api/v1/assets/:id/request-review	Submit asset for review	BearerAuth
POST	/api/v1/assets/:id/approve	Approve an asset	BearerAuth
POST	/api/v1/assets/:id/reject	Reject an asset with feedback	BearerAuth
GET	/api/v1/assets/approval-queue	View pending approval queue	BearerAuth
GET	/api/v1/assets/rejected-feedback	View rejection feedback	BearerAuth

Identity & Access Management (iam)

User management, authentication, roles, API keys, and project membership.

Method	Path	Summary	Auth
GET	/api/v1/auth/me	Get current user profile and permissions	BearerAuth
POST	/api/v1/auth/login	Authenticate with email/password	None
POST	/api/v1/auth/refresh	Refresh access token	None
POST	/api/v1/auth/revoke	Revoke a refresh token	BearerAuth
POST	/api/v1/auth/bootstrap	Create initial super_admin (one-time)	None
POST	/api/v1/auth/register	Self-registration (when enabled)	None
PUT	/api/v1/auth/password	Change own password	BearerAuth
POST	/api/v1/auth/reset-password	Admin reset user password	BearerAuth (admin)
GET	/api/v1/auth/token	Get token via refresh token	None
POST	/api/v1/users	Create user	BearerAuth (admin)
GET	/api/v1/users	List users	BearerAuth
GET	/api/v1/users/:id	Get user details	BearerAuth
PUT	/api/v1/users/:id/status	Update user status	BearerAuth (admin)
PUT	/api/v1/users/:id/roles	Update user roles	BearerAuth (admin)
POST	/api/v1/projects/:projectId/members	Add project member	BearerAuth (production+)
GET	/api/v1/projects/:projectId/members	List project members	BearerAuth
DELETE	/api/v1/projects/:projectId/members/:userId	Remove project member	BearerAuth (production+)
PUT	/api/v1/projects/:projectId/members/:userId/role	Change member role	BearerAuth (production+)
POST	/api/v1/api-keys	Create API key	BearerAuth
GET	/api/v1/api-keys	List API keys	BearerAuth
DELETE	/api/v1/api-keys/:id	Revoke API key	BearerAuth

Admin (admin)

Privileged administrative operations.

Method	Path	Summary	Auth
POST	/api/v1/iam/transfer-super-admin	Transfer super_admin role	BearerAuth (super_admin)

SCIM 2.0 (scim)

Identity provider provisioning endpoints (RFC 7644).

Method	Path	Summary	Auth
GET	/scim/v2/Users	List SCIM users	ScimTokenAuth
POST	/scim/v2/Users	Create SCIM user	ScimTokenAuth
GET	/scim/v2/Users/:id	Get SCIM user	ScimTokenAuth
PUT	/scim/v2/Users/:id	Replace SCIM user	ScimTokenAuth
PATCH	/scim/v2/Users/:id	Patch SCIM user	ScimTokenAuth
DELETE	/scim/v2/Users/:id	Deactivate SCIM user	ScimTokenAuth
GET	/scim/v2/Groups	List SCIM groups	ScimTokenAuth
POST	/scim/v2/Groups	Create SCIM group	ScimTokenAuth
GET	/scim/v2/ServiceProviderConfig	SCIM service provider config	ScimTokenAuth

Platform (platform)

Health checks, configuration, and platform settings.

Method	Path	Summary	Auth
GET	/health	Liveness probe	None
GET	/health/ready	Readiness probe with persistence check	None
GET	/api/v1/platform/settings	Get platform settings	BearerAuth
PUT	/api/v1/platform/settings	Update platform settings	BearerAuth (admin)

VFX Hierarchy (hierarchy)

Project, sequence, and shot management.

Method	Path	Summary	Auth
GET	/api/v1/hierarchy	Get full project hierarchy tree	BearerAuth
POST	/api/v1/hierarchy/projects	Create project	BearerAuth
POST	/api/v1/hierarchy/projects/:projectId/sequences	Create sequence	BearerAuth
POST	/api/v1/hierarchy/projects/:projectId/sequences/:sequenceId/shots	Create shot	BearerAuth

Review & Approval (review, review-sessions, comments, workflow)

Review session management, comments, and approval workflows.

Method	Path	Summary	Auth
GET	/api/v1/assets/:id/review-uri	Get review playback URI	BearerAuth
POST	/api/v1/review-sessions	Create review session	BearerAuth
GET	/api/v1/review-sessions	List review sessions	BearerAuth
GET	/api/v1/review-sessions/:id	Get review session detail	BearerAuth
POST	/api/v1/review-sessions/:id/submissions	Submit to review session	BearerAuth
POST	/api/v1/review-sessions/:id/close	Close review session	BearerAuth
POST	/api/v1/reviews/:sessionId/comments	Add review comment	BearerAuth
GET	/api/v1/reviews/:sessionId/comments	List review comments	BearerAuth
PUT	/api/v1/comments/:id/resolve	Resolve a comment	BearerAuth

Collections & Playlists (collections, playlists)

Curated groupings for review and delivery.

Method	Path	Summary	Auth
POST	/api/v1/collections	Create collection	BearerAuth
GET	/api/v1/collections	List collections	BearerAuth
GET	/api/v1/collections/:id	Get collection detail	BearerAuth
POST	/api/v1/playlists	Create playlist	BearerAuth
GET	/api/v1/playlists	List playlists	BearerAuth
GET	/api/v1/playlists/:id	Get playlist detail	BearerAuth

Materials & Timelines (materials, timelines)

MaterialX shaders and editorial timelines.

Method	Path	Summary	Auth
POST	/api/v1/materials	Create material	BearerAuth
GET	/api/v1/materials	List materials	BearerAuth
GET	/api/v1/materials/:id	Get material detail	BearerAuth
POST	/api/v1/timelines	Create timeline	BearerAuth
GET	/api/v1/timelines	List timelines	BearerAuth
GET	/api/v1/timelines/:id	Get timeline detail	BearerAuth

Provenance, Lineage & Dependencies (provenance, lineage, dependencies)

Asset lineage tracking and dependency graphs.

Method	Path	Summary	Auth
GET	/api/v1/provenance/:assetId	Get asset provenance	BearerAuth
GET	/api/v1/lineage/:assetId	Get lineage graph	BearerAuth
POST	/api/v1/dependencies	Create dependency	BearerAuth
GET	/api/v1/dependencies/:assetId	Get asset dependencies	BearerAuth

Job Queue & DLQ (pipeline, dlq)

Job processing, queue management, and dead-letter queue.

Method	Path	Summary	Auth
GET	/api/v1/jobs/:id	Get job details	BearerAuth
GET	/api/v1/jobs/pending	List pending jobs	BearerAuth
POST	/api/v1/jobs/:id/heartbeat	Worker heartbeat	ApiKeyAuth
POST	/api/v1/jobs/:id/replay	Replay a failed job	ApiKeyAuth
POST	/api/v1/queue/claim	Claim a job from the queue	ApiKeyAuth
POST	/api/v1/queue/reap-stale	Reap stale job leases	ApiKeyAuth
GET	/api/v1/dlq	List dead-letter queue jobs	BearerAuth
GET	/api/v1/dlq/:jobId	Get DLQ job detail	BearerAuth
POST	/api/v1/dlq/:jobId/replay	Replay DLQ job	BearerAuth
POST	/api/v1/dlq/replay-all	Replay all DLQ jobs	BearerAuth
DELETE	/api/v1/dlq/purge	Purge the DLQ	BearerAuth

Events (events)

Event ingestion, SSE streaming, and outbox publishing.

Method	Path	Summary	Auth
POST	/api/v1/events	Ingest a workflow event	ApiKeyAuth
POST	/api/v1/events/vast-dataengine	Receive VAST DataEngine callback	ApiKeyAuth
GET	/api/v1/events/stream	SSE event stream (persistent connection)	None*
GET	/api/v1/outbox	List pending outbox items	BearerAuth
POST	/api/v1/outbox/publish	Publish outbox to event broker	BearerAuth

* SSE stream checks x-api-key when SPACEHARBOR_API_KEY is configured.

Capacity & Analytics (capacity, analytics, catalog)

Storage metrics, analytics dashboards, and VAST catalog queries.

Method	Path	Summary	Auth
GET	/api/v1/capacity/storage-summary	Storage usage summary	BearerAuth
GET	/api/v1/capacity/footprint	Storage footprint by project	BearerAuth
GET	/api/v1/capacity/forecast	Storage growth forecast	BearerAuth
GET	/api/v1/analytics/dashboard	Dashboard analytics	BearerAuth
GET	/api/v1/catalog/views	List VAST views	BearerAuth
GET	/api/v1/catalog/buckets	List VAST buckets	BearerAuth

DataEngine (dataengine)

VAST DataEngine function registry.

Method	Path	Summary	Auth
GET	/api/v1/dataengine/functions	List registered functions	BearerAuth
GET	/api/v1/dataengine/functions/:id	Get function detail	BearerAuth
POST	/api/v1/dataengine/functions/:id/execute	Execute a function	BearerAuth

Observability (observability)

Metrics and monitoring.

Method	Path	Summary	Auth
GET	/api/v1/metrics	Workflow reliability counters	BearerAuth
GET	/api/v1/metrics/iam	IAM authorization metrics	BearerAuth

Audit (audit)

Authorization decision audit log.

Method	Path	Summary	Auth
GET	/api/v1/audit	Query audit log	BearerAuth
GET	/api/v1/audit/auth-decisions	Query IAM auth decisions (paginated)	BearerAuth

Work & Delivery (work, production)

Shot task assignments and delivery tracking.

Method	Path	Summary	Auth
GET	/api/v1/work/assignments	List work assignments	BearerAuth
GET	/api/v1/shots/:id/tasks	List shot tasks	BearerAuth
GET	/api/v1/delivery/packages	List delivery packages	BearerAuth

Incident Coordination (operations)

Operational incident management.

Method	Path	Summary	Auth
GET	/api/v1/incident/coordination	Get incident coordination state	BearerAuth
PUT	/api/v1/incident/coordination/actions	Execute incident action	ApiKeyAuth
POST	/api/v1/incident/coordination/notes	Add incident note	ApiKeyAuth
PUT	/api/v1/incident/coordination/handoff	Hand off incident	ApiKeyAuth

DCC Integration (dcc) [Deprecated]

DCC plugin endpoints. These are marked deprecated: true in the OpenAPI spec.

Method	Path	Summary	Auth
POST	/api/v1/dcc/checkin	DCC asset check-in	ApiKeyAuth
POST	/api/v1/dcc/checkout	DCC asset check-out	ApiKeyAuth
GET	/api/v1/dcc/status/:assetId	DCC lock status	ApiKeyAuth
POST	/api/v1/dcc/heartbeat	DCC session heartbeat	ApiKeyAuth

SQL Query Console (admin)

Direct SQL queries against VAST Database (restricted, JWT-only, audited).

Method	Path	Summary	Auth
POST	/api/v1/query/execute	Execute SQL query	BearerAuth (JWT only)
GET	/api/v1/query/history	Query execution history	BearerAuth
DELETE	/api/v1/query/:queryId	Cancel running query	BearerAuth

Error Handling

All error responses use a consistent envelope:

{
  "code": "UNAUTHORIZED",
  "message": "authentication required",
  "requestId": "req-42",
  "details": null
}

Standard Error Codes

Code	HTTP Status	Meaning
BAD_REQUEST	400	Invalid input or missing required fields
UNAUTHORIZED	401	Missing or invalid credentials
FORBIDDEN	403	Valid credentials but insufficient permissions
NOT_FOUND	404	Resource does not exist
CONFLICT	409	State conflict (e.g., duplicate email)
GONE	410	Resource permanently unavailable (e.g., bootstrap already completed)
HTTPS_REQUIRED	421	TLS enforcement rejection
RATE_LIMITED	429	Too many requests
INTERNAL_ERROR	500	Server error (fail-closed)
SERVICE_UNAVAILABLE	503	Dependency unavailable (e.g., VAST Database)

Correlation ID

Every response includes x-correlation-id in the response headers. Send x-correlation-id in requests to trace operations across services.

Pagination

List endpoints support pagination via query parameters:

Parameter	Type	Default	Description
limit	number	50	Items per page (max 500)
offset	number	0	Skip N items
sort	string	varies	Sort field
order	string	desc	Sort order (asc / desc)

Response includes pagination metadata:

{
  "items": [...],
  "total": 142,
  "limit": 50,
  "offset": 0
}

See Also

• Architecture Overview — System design and data flow
• Identity and Access — Detailed IAM documentation
• Configuration Guide — Environment variables reference
• Pipeline and Functions — DataEngine function details
• Security — Security posture and hardening