API Examples

API Examples

Practical examples for common SpaceHarbor API workflows. All examples use http://localhost:8080 (default dev port).

Swagger UI: http://localhost:8080/api/docs OpenAPI Spec: http://localhost:8080/openapi.json

---

Authentication

Login and Get Token

TOKEN=$(curl -s -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@spaceharbor.dev","password":"Admin1234!dev"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['accessToken'])")

echo "Token: ${TOKEN:0:20}..."

Use Token in Requests

curl -s http://localhost:8080/api/v1/assets \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

---

Asset Ingest Workflow

1. Ingest an Asset

curl -s -X POST http://localhost:8080/api/v1/assets/ingest \
  -H "x-api-key: sh_your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "hero_comp_v003",
    "sourceUri": "s3://vfx-bucket/shots/SH001/hero_comp_v003.exr",
    "metadata": {
      "show": "Project Alpha",
      "sequence": "SEQ010",
      "shot": "SH001",
      "version": "v003",
      "artist": "jane.doe@studio.com"
    }
  }'

Response (201):

{
  "asset": {
    "id": "7f8e5c3a-2b1d-4e6f-9a8c-3d2e1f0a9b8c",
    "title": "hero_comp_v003",
    "status": "ingest",
    "elementHandle": "elem_abc123xyz",
    "createdAt": "2026-03-24T10:30:00.000Z"
  },
  "job": {
    "id": "job-uuid",
    "status": "pending"
  }
}

2. Check Processing Status

ASSET_ID="7f8e5c3a-2b1d-4e6f-9a8c-3d2e1f0a9b8c"

curl -s http://localhost:8080/api/v1/assets/$ASSET_ID/pipeline-status \
  -H "Authorization: Bearer $TOKEN"

3. Submit for Review

curl -s -X POST http://localhost:8080/api/v1/assets/$ASSET_ID/request-review \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Ready for supervisor review"}'

4. Approve

curl -s -X POST http://localhost:8080/api/v1/assets/$ASSET_ID/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes": "Approved for delivery"}'

---

Worker Job Processing

Claim a Job

curl -s -X POST http://localhost:8080/api/v1/queue/claim \
  -H "x-api-key: sh_worker-key" \
  -H "Content-Type: application/json" \
  -d '{"workerId": "worker-1", "jobTypes": ["probe", "transcode"]}'

Send Heartbeat

JOB_ID="job-uuid"

curl -s -X POST http://localhost:8080/api/v1/jobs/$JOB_ID/heartbeat \
  -H "x-api-key: sh_worker-key" \
  -H "Content-Type: application/json" \
  -d '{"workerId": "worker-1", "progress": 65}'

---

Review Sessions

Create a Review Session

curl -s -X POST http://localhost:8080/api/v1/review-sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dailies - March 24",
    "projectId": "project-uuid",
    "reviewers": ["supervisor@studio.com"]
  }'

Add a Comment

SESSION_ID="session-uuid"

curl -s -X POST http://localhost:8080/api/v1/reviews/$SESSION_ID/comments \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assetId": "asset-uuid",
    "timecode": "01:02:15:03",
    "text": "Edge artifact on the left side of the comp"
  }'

---

User Management

Create a User

curl -s -X POST http://localhost:8080/api/v1/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "artist@studio.com",
    "displayName": "Jane Artist",
    "role": "artist"
  }'

Add User to Project

curl -s -X POST http://localhost:8080/api/v1/projects/project-uuid/members \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-uuid", "role": "artist"}'

---

VFX Hierarchy

Create Project Structure

# Create project
curl -s -X POST http://localhost:8080/api/v1/hierarchy/projects \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Project Alpha", "code": "ALPHA"}'

# Create sequence
curl -s -X POST http://localhost:8080/api/v1/hierarchy/projects/ALPHA/sequences \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "SEQ010", "description": "Opening sequence"}'

# Create shot
curl -s -X POST http://localhost:8080/api/v1/hierarchy/projects/ALPHA/sequences/SEQ010/shots \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "SH001", "frameRange": "1001-1120"}'

---

Monitoring

Health Check

curl -s http://localhost:8080/health | python3 -m json.tool

Workflow Metrics

curl -s http://localhost:8080/api/v1/metrics \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

DLQ Status

curl -s http://localhost:8080/api/v1/dlq \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool

---

SSE Event Stream

Subscribe to Real-Time Events

curl -N http://localhost:8080/api/v1/events/stream \
  -H "x-api-key: sh_your-key"

From JavaScript:

const es = new EventSource('http://localhost:8080/api/v1/events/stream');
es.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.type, data);
};

---

OpenAPI Spec Usage

Download Spec

curl -s http://localhost:8080/openapi.json -o openapi.json

Generate TypeScript Client

npx openapi-typescript http://localhost:8080/openapi.json -o api-types.ts

View in Swagger UI

Open http://localhost:8080/api/docs in your browser.

---

See Also

• API Overview — Access paths and structure
• API Authentication — Auth flow details
• API Endpoint Groups — Full endpoint reference
• API Error Handling — Error codes and pagination