Orgs
Console

Documentation

API Reference

Production API routes available at https://api.orgs.sh, including authentication, entity lifecycle, proposals, formation, and billing.

Base URL and auth

The production API base URL is https://api.orgs.sh. Protected routes require Authorization: Bearer credentials.

  • Health is public.
  • Entity, proposal, formation, and billing read/upgrade routes require bearer auth.
  • Webhook routes use their own HMAC verification path.
curl -sS https://api.orgs.sh/health

curl -sS https://api.orgs.sh/v1/entities \
  -H "authorization: Bearer $ORGS_API_KEY"

Accounts

Create an account to bootstrap API-key access. The raw API key is returned once in the response.

  • 201 response: id, email, api_key.
  • 400 response: invalid email.
POST /v1/accounts
{
  "email": "operator@example.com"
}

Entities

Entities are account-owned resources. Cross-account access returns not found to prevent enumeration.

  • POST body: constitution_yaml.
  • PUT body: action, optional filing_error, version.
  • Version conflicts return 409.
  • Invalid entity UUIDs return 400.
GET    /v1/entities
POST   /v1/entities
GET    /v1/entities/{id}
PUT    /v1/entities/{id}
DELETE /v1/entities/{id}

Proposals

Create proposals under an entity. The server evaluates constitution policy and can return an escalation reason.

  • Supported kinds: spend, hire_agent, dissolution.
  • Spend requires amount_usd and recipient.
  • Response includes id, title, proposal_type, state, escalation.
POST /v1/entities/{id}/proposals
{
  "kind": "spend",
  "title": "Pay invoice",
  "description": "Registered-agent renewal",
  "amount_usd": 125,
  "recipient": "registered-agent"
}

Formation

Formation routes move an entity into filing and report current filing status.

  • Start is idempotent for entities already filing.
  • Status includes state, filing_number, EIN, and filing_error.
  • The filing worker performs the external filing after the state transition.
POST /v1/entities/{id}/formation/start
GET  /v1/entities/{id}/formation/status

Billing

Billing routes are account-scoped and authenticated except for provider webhook handling.

GET  /v1/billing/subscription
GET  /v1/billing/usage
POST /v1/billing/upgrade
POST /v1/billing/webhook
Documentation - Orgs