REST API

The Rust Axum backend exposes a REST API for all corporate operations.

Base URL

• Hosted: https://api.thecorporation.ai
• Local dev: http://localhost:8000

OpenAPI spec:

GET /openapi.json

Authentication

All requests require a Bearer token — either a JWT (HS256) or an API key (Argon2-hashed, issued via the admin domain).

curl -H "Authorization: Bearer $CORP_TOKEN" \
  https://api.thecorporation.ai/v1/entities

Token types:

• JWT — short-lived, issued via POST /auth/token
• API key — long-lived, managed via POST /admin/api-keys

Scopes

API keys carry one or more scopes that restrict what operations they can perform:

Scope	Access
formation-create / formation-read	Create and read entities
equity-read / equity-write	Cap table and round operations
governance-read / governance-write	Meetings, votes, resolutions
treasury-read / treasury-write	Invoices, payments, payroll
contacts-read / contacts-write	Stakeholder directory
admin	Key management, user admin
all	Full access (superuser)

Domain groups

Domain	Base path	Description
Formation	/formation	Entity creation, structure, documents
Equity	/equity	Cap table, rounds, conversions, SAFEs
Governance	/governance	Meetings, votes, board actions
Treasury	/treasury	Invoices, payments, payroll, bank accounts
Execution	/execution	Intents, receipts, async mutation lifecycle
Contacts	/contacts	Stakeholder and signer directory
Agents	/agents	Autonomous agent definitions and runs
Work Items	/work_items	Tasks and tracked work
Services	/services	Integrations and external service configs
Admin	/admin	API keys, users, workspace settings

Execution lifecycle

Mutations that require authorization flow through typed intents:

POST /execution/intents
POST /execution/intents/{intent_id}/evaluate
POST /execution/intents/{intent_id}/authorize
POST /execution/intents/{intent_id}/execute
GET  /execution/receipts/{receipt_id}

Idempotency is enforced with an Idempotency-Key header on execute requests.

Example requests

# List entities
curl -H "Authorization: Bearer $CORP_TOKEN" \
  https://api.thecorporation.ai/v1/entities

# Create an entity
curl -X POST \
  -H "Authorization: Bearer $CORP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"legal_name":"Acme Corp","entity_type":"c_corp","jurisdiction":"DE"}' \
  https://api.thecorporation.ai/v1/entities

# Get cap table
curl -H "Authorization: Bearer $CORP_TOKEN" \
  https://api.thecorporation.ai/v1/entities/{entity_id}/cap-table

# List governance meetings
curl -H "Authorization: Bearer $CORP_TOKEN" \
  https://api.thecorporation.ai/v1/entities/{entity_id}/governance/meetings

Storage backends

The server supports two storage backends, configured at startup:

• git (default) — every mutation is a git commit; full audit log is the repository history
• kv + s3 — Redis for hot state, S3 for document blobs; suited for high-write workloads

See Self-Hosting for backend configuration details.

See API Endpoints for the full generated endpoint inventory.