Skip to content

REST API

Reference
On this page
  1. Base URL
  2. Authentication
  3. Conventions
  4. Common endpoints
  5. Auth
  6. Orgs + members
  7. Cloud accounts
  8. Deployments
  9. Sessions (chat with agents)
  10. Agents
  11. Notifications
  12. Audit log
  13. Billing
  14. Public config (no auth required)
  15. OIDC issuer (no auth required — public)
  16. Rate limits
  17. Example: full end-to-end deployment via API
  18. SDKs
  19. See also

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

Note
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://api.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:

terminal
# From DevTools console in the orchestrator UI:
copy(localStorage.getItem('auth_token'))
 
# Or via curl:
curl -X POST https://api.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:

json
{
  "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 classLimit
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 reads600/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

terminal
TOKEN="eyJ..."   # your JWT
 
# 1. List your cloud accounts
curl -s https://api.hivedeploy.in/api/clouds \
  -H "Authorization: Bearer $TOKEN" | jq
 
# 2. Start a Postgres deployment session
SESSION=$(curl -s -X POST https://api.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://api.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://api.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.

See also

Was this page helpful?