API Overview

API Overview

SpaceHarbor exposes a REST API through the control-plane service. All API operations — asset management, identity, review workflows, pipeline monitoring, and administration — are available through this single service.

Canonical Paths

Resource	Path	Description
API Base	/api/v1/	Versioned API namespace
Swagger UI	/api/docs	Interactive documentation with "Try it out"
OpenAPI Spec	/openapi.json	Machine-readable OpenAPI 3.0.3 (JSON)

Base URL

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

API Versioning

Routes are registered under two prefixes:

• /api/v1/... — Versioned (recommended for all integrations)
• /... — Legacy (identical behavior, will be removed in a future major version)

Always use the /api/v1/ prefix for new integrations.

Accessing API Documentation

Swagger UI (Interactive)

Open in your browser:

http://localhost:8080/api/docs

Swagger UI provides:

• Full endpoint listing organized by tags
• Request/response schema documentation
• "Try it out" for live API testing
• Authentication header configuration

Swagger UI is available in all environments (development and production). It is explicitly exempt from IAM authentication.

OpenAPI Spec (Machine-Readable)

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

# View path count
curl -s http://localhost:8080/openapi.json | python3 -c \
  "import sys,json; print(len(json.load(sys.stdin)['paths']), 'paths')"

The spec is generated dynamically at runtime from route schema decorations. A static snapshot is also committed at docs/openapi-snapshot.json in the repository.

Spec Details

• Format: OpenAPI 3.0.3
• Title: SpaceHarbor API
• Paths: 270+
• Tags: 33 endpoint groups
• Security Schemes: 4 (BearerAuth, ApiKeyAuth, ServiceTokenAuth, ScimTokenAuth)

API Structure

The API is organized into these functional groups:

Group	Tag	Description
Asset Management	assets	Ingest, browse, search, approve media assets
Identity & Access	iam	Users, roles, login, API keys, project membership
Review & Approval	review, review-sessions, comments	Review sessions, annotations, approval workflows
VFX Hierarchy	hierarchy	Projects, sequences, shots
Pipeline & Jobs	pipeline, dlq	Job processing, queue, dead-letter queue
Events	events	Event ingestion, SSE streaming, outbox
Materials & Timelines	materials, timelines	MaterialX shaders, OTIO editorial timelines
Provenance & Lineage	provenance, lineage, dependencies	Asset lineage and dependency graphs
Collections & Playlists	collections, playlists	Curated groupings for review and delivery
Capacity & Analytics	capacity, analytics, catalog	Storage metrics, dashboards, VAST catalog
DataEngine	dataengine	VAST DataEngine function registry
Observability	observability	Metrics and monitoring counters
Audit	audit	Authorization decision audit log
Administration	admin, platform	Settings, super_admin transfer, SQL console
SCIM 2.0	scim	Identity provider user/group provisioning
Work & Delivery	work, production	Shot tasks, assignments, delivery packages
Incident Ops	operations	Incident coordination and handoff
DCC Integration	dcc	DCC plugin endpoints (deprecated)

Quick Start

# 1. Check health (no auth required)
curl http://localhost:8080/health

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

# 3. Use the returned accessToken
curl http://localhost:8080/api/v1/assets \
  -H "Authorization: Bearer <accessToken>"

# 4. Browse the interactive docs
open http://localhost:8080/api/docs

See Also

• API Authentication — Security schemes, login flow, public endpoints
• API Endpoint Groups — Full endpoint reference by category
• API Error Handling — Error codes, envelope format, pagination
• API Examples — Practical usage examples
• API Reference — Comprehensive flat endpoint listing