REST API Overview

The PrintStudio REST API is a Hono application running on Bun. It exposes 100+ endpoints for every domain operation: orders, jobs, printers, SKUs, inventory, analytics, and system management.

Base URL

Environment	URL
Local dev	http://localhost:8787
Production	Your deployed API URL

Interactive Documentation

The API includes a full OpenAPI 3.1 spec and an interactive explorer powered by Scalar:

• OpenAPI JSON: http://localhost:8787/openapi.json
• Scalar UI: http://localhost:8787/docs

Open http://localhost:8787/docs in your browser to explore and test every endpoint without writing any code.

Versioning

The API is currently unversioned (no /v1/ prefix). Breaking changes will introduce versioning at that point. All endpoints are under /api/* except:

Path	Purpose
/	Health check
/openapi.json	OpenAPI spec
/docs	Scalar interactive docs
/webhooks/*	Inbound webhooks (Stripe, OpenClaw)
/api/*	All application endpoints

Content Type

All endpoints accept and return application/json. File uploads use multipart/form-data.

Error Format

All errors follow a consistent shape:

{
  "error": "Not found",
  "code": "JOB_NOT_FOUND",
  "details": {
    "jobId": "job-abc-123"
  }
}

HTTP status codes follow REST conventions: 200 success, 201 created, 400 validation error, 401 unauthenticated, 403 forbidden, 404 not found, 409 conflict, 500 server error.

Rate Limiting

Default rate limits (configurable via env):

Tier	Limit
Unauthenticated	20 req/min
API Key (standard)	300 req/min
API Key (admin)	1000 req/min

Rate limit headers are included on every response:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1700000060

Endpoint Groups

Group	Prefix	Description
Authentication	/api/auth	Login, logout, API key management
Orders	/api/orders	Order CRUD + state management
Jobs	/api/jobs	Job management + state transitions
Printers	/api/printers	Fleet management
SKUs	/api/skus	Product catalog
Inventory	/api/inventory	Material stock
Customers	/api/customers	Customer records
Analytics	/api/analytics	Metrics and reports
Orchestrator	/api/orchestrator	AutoPilot control
Setup	/api/setup	First-run configuration
Webhooks	/webhooks	Inbound webhook receivers

Quick Test

# Health check (no auth required)
curl http://localhost:8787/

# List all SKUs (auth required)
curl http://localhost:8787/api/skus \
  -H "X-API-Key: your-api-key"