REST API

The orchestrator’s backend exposes a REST API. The web frontend uses this same API — anything the UI can do, the API can do.

the API is internal-grade as of May 2026. Endpoints are stable but undocumented at the public-spec level (no OpenAPI spec published yet). If you build against it, expect to handle breaking changes per release. A public versioned API is on the roadmap.

Base URL

https://backend.hivedeploy.in

Authentication

Every authenticated endpoint takes:

Authorization: Bearer <JWT>

The JWT comes from the login endpoint or from your browser’s localStorage.auth_token (which is set after you sign in via the UI).

Get your JWT:

# From DevTools console in the orchestrator UI:
copy(localStorage.getItem('auth_token'))
 
# Or via curl:
curl -X POST https://backend.hivedeploy.in/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "password": "..."}'
# Returns: { "access_token": "eyJ...", "user": { ... } }

JWTs are valid for 12 hours by default.

Conventions

All endpoints return JSON
Errors are {"detail": "..."} with HTTP status codes (4xx for client error, 5xx for server error)
Pagination uses ?cursor=...&limit=N where applicable; responses include next_cursor
IDs are prefixed strings: o-... for orgs, u-... for users, deploy-... for deployments, ca-... for cloud accounts, etc.
Timestamps are ISO 8601 UTC

Common endpoints

Auth

POST   /api/auth/signup              create account
POST   /api/auth/login                authenticate
POST   /api/auth/verify-email         consume email-verify token
POST   /api/auth/forgot-password      request reset link
POST   /api/auth/reset                consume reset token
POST   /api/auth/logout               (idempotent; just discard token client-side)
GET    /api/auth/me                   current user info
GET    /api/auth/me/onboarding-status onboarding state (plan picker etc.)
POST   /api/auth/switch-org           re-issue JWT for a different org

Orgs + members

GET    /api/orgs/me                   orgs the current user is a member of
GET    /api/orgs/current              current org (set by JWT's org_id)
PATCH  /api/orgs/current              update org name / settings (Owner/Admin)
GET    /api/orgs/current/members      list members
POST   /api/orgs/current/invites      send invite (Owner/Admin)
GET    /api/orgs/current/invites      list pending invites
DELETE /api/orgs/current/invites/:id  cancel invite
POST   /api/orgs/invites/:token/accept accept (called by the invitee)
PATCH  /api/orgs/current/members/:id  change role (Owner)
DELETE /api/orgs/current/members/:id  remove member

Cloud accounts

GET    /api/clouds                    list connected cloud accounts
POST   /api/clouds                    connect a new account (probes first)
GET    /api/clouds/:id                cloud account details
DELETE /api/clouds/:id                disconnect

Request body for POST /api/clouds:

{
  "provider": "gcp",
  "accountLabel": "prod-gcp",
  "credentials": {
    "kind": "workload_identity",
    "projectId": "your-project-abc123",
    "providerResource": "projects/.../providers/orch-provider",
    "serviceAccount": "orch-deployer@your-project-abc123.iam.gserviceaccount.com"
  },
  "defaultRegion": "us-central1"
}

(See Connect AWS / Connect Azure for those credential shapes.)

Deployments

GET    /api/deployments               list deployments (paginated)
POST   /api/deployments               start a new deployment
GET    /api/deployments/:id           deployment details + current gate
PATCH  /api/deployments/:id           update scope / labels / etc.
POST   /api/deployments/:id/approve   approve at current gate (Admin)
POST   /api/deployments/:id/reject    reject at current gate (Admin)
POST   /api/deployments/:id/destroy   tear down resources

Sessions (chat with agents)

GET    /api/sessions                       list sessions
POST   /api/sessions                       start a new session
GET    /api/sessions/:id                   session details + messages
POST   /api/sessions/:id/messages          post a user message (returns SSE stream)
GET    /api/sessions/:id/messages          fetch history paginated

Posting to /api/sessions/:id/messages returns Server-Sent Events streaming the assistant’s response token-by-token. Set Accept: text/event-stream and parse with an SSE client library.

Agents

GET    /api/agents                    list all specialist agents
GET    /api/agents/:id                agent metadata (description, supported clouds)

Notifications

GET    /api/notifications             paginated feed (?unread_only=true)
POST   /api/notifications/:id/read    mark as read
POST   /api/notifications/:id/unread  mark as unread
POST   /api/notifications/mark-all-read
GET    /api/notifications/unread_count count of unread

Audit log

GET    /api/audit                     paginated audit events

Query params:

?actor_id=u-...
?action=deployment.applied
?from=2026-01-01T00:00:00Z
?to=2026-01-31T23:59:59Z

Billing

GET    /api/billing/state             current plan, usage, limits
GET    /api/billing/plans             list available plans
GET    /api/billing/invoices          past invoices
PATCH  /api/billing/cap               update overage cap
POST   /api/billing/checkout          start upgrade checkout
POST   /api/billing/portal            open customer portal

Public config (no auth required)

GET    /api/config/public             feature flags + Turnstile site key, etc.

OIDC issuer (no auth required — public)

GET    /.well-known/openid-configuration
GET    /.well-known/jwks.json

These exist for customer cloud WIF providers to discover and verify the orchestrator’s JWTs. Customer-facing; no JWT needed to fetch.

Rate limits

Endpoint class	Limit
Auth endpoints (login, signup, forgot-password)	10/min per IP
Session message posts (LLM-calling)	10/min per user; subject to plan-credit limits
All other authenticated reads	600/min per user
Webhook deliveries (outbound from us)	Unlimited but with exponential backoff

Limits are sliding-window. When you hit a limit, you get 429 Too Many Requests with a Retry-After header (seconds).

Example: full end-to-end deployment via API

TOKEN="eyJ..."   # your JWT
 
# 1. List your cloud accounts
curl -s https://backend.hivedeploy.in/api/clouds \
  -H "Authorization: Bearer $TOKEN" | jq
 
# 2. Start a Postgres deployment session
SESSION=$(curl -s -X POST https://backend.hivedeploy.in/api/sessions \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "postgres"}' | jq -r '.id')
 
# 3. Send the first message (Gate 1 intent)
curl -N -X POST https://backend.hivedeploy.in/api/sessions/$SESSION/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{"text": "Main app database for a Python web service serving ~500 RPS"}'
 
# Response streams via SSE. Read until [DONE] event.
 
# 4. Check current gate
curl -s https://backend.hivedeploy.in/api/sessions/$SESSION \
  -H "Authorization: Bearer $TOKEN" | jq '.current_gate'
 
# 5. ... continue dialogue, advance through gates, apply at Gate 6

SDKs

None yet. Roadmap includes:

TypeScript SDK (npm) — Q3 2026
Python SDK (PyPI) — Q3 2026
Go SDK — TBD based on demand

For now, treat the API as raw REST + SSE.