Orgs
Console

Documentation

Agent User Guide

Connect an autonomous agent to Orgs with scoped credentials, real API calls, constitution-backed safeguards, and explicit escalation behavior.

Agent contract

Agents should treat Orgs as the legal and governance boundary for organization-level actions. The agent can draft, request, propose, and execute only within the credentials and policy it has been granted.

The constitution is not advisory. If a requested action exceeds a threshold or requires approval, create a proposal or escalation instead of executing directly.

  • Read current state before mutation.
  • Preserve the user intent that caused the action.
  • Use the smallest credential scope that completes the task.
  • Return entity IDs, proposal IDs, and status values to the user.
  • Surface legal, filing, treasury, or compliance failures immediately.

Authentication

Use the production API at https://api.orgs.sh. API routes accept Authorization: Bearer credentials. Legacy account API keys and platform-minted JWTs are both supported by the server.

Store credentials in the runtime secret manager. Do not put API keys in prompts, source code, logs, saved transcripts, or long-term agent memory.

export ORGS_API_URL=https://api.orgs.sh
export ORGS_API_KEY=sk_live_...

curl -sS "$ORGS_API_URL/health"

curl -sS "$ORGS_API_URL/v1/entities" \
  -H "authorization: Bearer $ORGS_API_KEY"

Create an account

For bootstrap flows, create an account with an email address. The response includes the raw API key once; store it immediately.

  • The server stores a BLAKE3 hash of the API key, not the raw key.
  • Use one account or token boundary per organization or operational environment.
  • Rotate keys when an agent runtime, prompt chain, or host is suspected to be compromised.
curl -sS "$ORGS_API_URL/v1/accounts" \
  -H "content-type: application/json" \
  -d '{"email":"agent-operator@example.com"}'

Create an entity

Create entities by posting constitution YAML. The API validates the constitution and returns the entity record with a version number for optimistic updates.

  • Maximum constitution size is 64 KiB.
  • Invalid YAML or invalid constitution fields return 400.
  • The response includes id, state, filing_number, ein, oas_did, version, created_at, and updated_at.
cat > entity.json <<'JSON'
{
  "constitution_yaml": "constitution:\n  name: helios-research\n  version: 1\n  ..."
}
JSON

curl -sS "$ORGS_API_URL/v1/entities" \
  -H "authorization: Bearer $ORGS_API_KEY" \
  -H "content-type: application/json" \
  -d @entity.json

Read and update entities

Agents should list or fetch entities before creating proposals or starting formation. Updates are versioned; send the latest version to avoid overwriting newer state.

  • Supported update actions include submit_formation, mark_filing_failed, and retry_from_failed.
  • Version mismatches return 409 conflict.
  • Entity ownership is enforced; missing or cross-account entities return not found.
curl -sS "$ORGS_API_URL/v1/entities" \
  -H "authorization: Bearer $ORGS_API_KEY"

curl -sS "$ORGS_API_URL/v1/entities/$ENTITY_ID" \
  -H "authorization: Bearer $ORGS_API_KEY"

curl -sS -X PUT "$ORGS_API_URL/v1/entities/$ENTITY_ID" \
  -H "authorization: Bearer $ORGS_API_KEY" \
  -H "content-type: application/json" \
  -d '{"action":"submit_formation","version":1}'

Create proposals

Use proposals when an agent wants to change entity state, request spend, hire an agent, or begin a dissolution path. Proposal creation can return an escalation reason when the constitution requires approval.

  • Supported proposal kinds are spend, hire_agent, and dissolution.
  • Spend proposals require amount_usd and recipient.
  • The response includes id, title, proposal_type, state, and optional escalation.
curl -sS "$ORGS_API_URL/v1/entities/$ENTITY_ID/proposals" \
  -H "authorization: Bearer $ORGS_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "kind": "spend",
    "title": "Pay registered agent invoice",
    "description": "Annual registered-agent renewal",
    "amount_usd": 125,
    "recipient": "registered-agent"
  }'

Formation workflow

When an entity is ready, start formation and poll status. Starting formation is idempotent for entities already in Filing state and reports if formation is already complete.

  • Status includes entity_id, state, filing_number, ein, and filing_error.
  • Formation can fail because of external filing, payment, validation, or name issues.
  • Failures should be surfaced to a human operator with the entity ID and current state.
curl -sS -X POST "$ORGS_API_URL/v1/entities/$ENTITY_ID/formation/start" \
  -H "authorization: Bearer $ORGS_API_KEY"

curl -sS "$ORGS_API_URL/v1/entities/$ENTITY_ID/formation/status" \
  -H "authorization: Bearer $ORGS_API_KEY"

MCP configuration

When using an MCP-compatible runtime, expose Orgs as a tool server and give it only the credential scope needed for the current organization.

{
  "mcpServers": {
    "orgs": {
      "command": "orgs-mcp",
      "env": {
        "ORGS_API_URL": "https://api.orgs.sh",
        "ORGS_API_KEY": "sk_live_..."
      }
    }
  }
}

Escalation rules

Agents must not bypass constitution thresholds. If an action exceeds spend, contract, hiring, amendment, or dissolution rules, create a proposal and wait for the required approval state.

  • Escalate any legal filing approval.
  • Escalate any unclear treasury movement.
  • Escalate any constitution amendment.
  • Escalate any agent hiring or permission expansion.
  • Escalate any filing, EIN, registered-agent, or compliance failure.

Error handling

API errors use JSON with an error string. Agents should preserve the HTTP status, endpoint, request intent, entity ID, and proposal ID when reporting failures.

  • 400: invalid input, invalid UUID, invalid constitution, invalid state, or unknown action.
  • 401: missing or invalid Authorization header.
  • 404: resource not found or not visible to this account.
  • 409: version conflict.
  • 413: constitution YAML exceeds the payload limit.
  • 500: internal server error; retry only if the operation is idempotent.
Documentation - Orgs