API Reference

Base URL

https://api.orbiocloud.com/api/v1

Authentication Endpoints

All auth endpoints require a publishable key (pk) in the X-API-Key header.

POST   /v1/auth/signup          Create a new user (email, password, metadata?)
POST   /v1/auth/signin          Sign in with email/password
POST   /v1/auth/signout         Revoke session (X-Access-Token required)
POST   /v1/auth/refresh         Refresh session tokens (refresh_token)
GET    /v1/auth/me              Get current user (X-Access-Token required)
POST   /v1/auth/reset-password  Send password reset email (email)
POST   /v1/auth/verify          Verify email/recovery token (token, type)

Collections Endpoints

Reads: pk or sk. Writes: sk with collections:write scope.

GET    /v1/collections                          List manifests (page, limit)
POST   /v1/collections                          Create manifest (slug, name, schema?)
GET    /v1/collections/{slug}                    Get manifest
PATCH  /v1/collections/{slug}                    Update manifest (name?, schema?)
DELETE /v1/collections/{slug}                    Delete manifest + documents
GET    /v1/collections/{slug}/documents           List documents (page, limit, filter?)
POST   /v1/collections/{slug}/documents           Create document (data)
GET    /v1/collections/{slug}/documents/{id}       Get document
PATCH  /v1/collections/{slug}/documents/{id}       Merge-patch document (data)
DELETE /v1/collections/{slug}/documents/{id}       Delete document

Storage Endpoints

Reads: pk or sk. Writes: sk with storage:write scope.

POST   /v1/storage/upload        Upload file (multipart/form-data)
GET    /v1/storage/files          List files (page, limit)
GET    /v1/storage/files/{id}     Get file + fresh signed URL
DELETE /v1/storage/files/{id}     Delete file

Billing Endpoints

All require pk or sk + X-Access-Token.

POST   /v1/billing/checkout      Create Stripe Checkout session (price_id, success_url, cancel_url)
GET    /v1/billing/subscription   Get current user subscription status
POST   /v1/billing/portal        Create Stripe Customer Portal session (return_url)

Realtime Endpoint

POST   /v1/realtime/token        Get Realtime authentication token (X-Access-Token required)

Webhook Endpoints

Reads: pk or sk. Writes: sk with webhooks:write scope.

GET    /v1/webhooks/endpoints           List endpoints (page, limit)
POST   /v1/webhooks/endpoints           Register endpoint (url, events?, description?)
GET    /v1/webhooks/endpoints/{id}       Get endpoint
PATCH  /v1/webhooks/endpoints/{id}       Update endpoint
DELETE /v1/webhooks/endpoints/{id}       Delete endpoint
GET    /v1/webhooks/deliveries           List deliveries (endpoint_id?, status?)

Response Format

All endpoints return a consistent JSON envelope:

// Success
{ "success": true, "data": { ... } }

// Paginated
{ "success": true, "data": { "items": [...], "page": 1, "limit": 20, "total": 42, "has_more": true } }

// Error
{ "success": false, "error": "Description" }

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 100       # Requests per window
X-RateLimit-Remaining: 97    # Remaining in current window
X-RateLimit-Reset: 1712345678 # Reset timestamp (epoch ms)

Error Codes

400  Bad Request       Invalid input or missing required fields
401  Unauthorized      Invalid API key or access token
402  Payment Required  Storage limit exceeded
403  Forbidden         Secret key required or missing scope
404  Not Found         Resource does not exist
409  Conflict          Duplicate (email, collection slug)
429  Too Many Requests Rate limit exceeded (see Retry-After header)
500  Internal Error    Server error (logged, not leaked)
503  Unavailable       ClamAV scanning service down