Organization and operations API

Use this reference to create organization boundaries and manage personal or organization-scoped vault entries. It also maps the related administrative API families to their task documentation so that permissions, side effects, and operational cautions stay with the workflow they govern.

Organization model

An organization is a shared tenant boundary. Its record includes id, name, unique slug, plan, optional billingEmail, settings, and timestamps. Related records can include members, roles, API keys, skills, executions, MCP servers, vault entries, triggers, schedules, audit logs, agent memories, and a budget policy.

Organization responses use the envelope { "success": true, "data": ... }. Authentication failures return 401; validation failures return 400. Authorization and not-found errors are produced by the shared API error handler for organization-service operations.

Organizations

List organizations

curl --request GET \
  --url https://agent-studio.example.com/api/organizations

{ "success": true, "data": [ { "id": "org_example", "name": "Example Support", "slug": "example-support" } ] }

curl 'https://agent-studio.example.com/api/organizations' \
  -H 'Cookie: __session=<session-cookie>'

Create an organization

curl --request POST \
  --url https://agent-studio.example.com/api/organizations \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example Support",
  "slug": "example-support",
  "plan": "free",
  "billingEmail": "billing@example.com"
}'

{ "success": true, "data": { "id": "org_example", "name": "Example Support", "slug": "example-support", "plan": "free" } }

Get an organization

curl --request GET \
  --url https://agent-studio.example.com/api/organizations/org_example

{ "success": true, "data": { "id": "org_example", "name": "Example Support", "slug": "example-support", "settings": {} } }

Update an organization

curl --request PUT \
  --url https://agent-studio.example.com/api/organizations/org_example \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Example Support Operations",
  "billingEmail": "operations@example.com",
  "settings": {}
}'

{ "success": true, "data": { "id": "org_example", "name": "Example Support Operations", "settings": {} } }

The update route does not accept slug or plan; omit fields that should remain unchanged.

Delete an organization

curl --request DELETE \
  --url https://agent-studio.example.com/api/organizations/org_example

{ "success": true }

Vault entries

Vault values are encrypted at rest. List responses are masked; the reveal operation returns plaintext and should be used only at the point of need. In organization context, owners and administrators can list all entries, members with vault:read:own see their own entries, and viewers without that permission receive an empty list.

List vault entries

curl --request GET \
  --url https://agent-studio.example.com/api/vault?q=support&organizationId=org_example \
  --header 'X-Organization-Id: org_example'

{ "success": true, "data": [ { "id": "vault_example", "name": "Support model key", "key": "SUPPORT_MODEL_KEY", "value": "********" } ] }

Create a vault entry

curl --request POST \
  --url https://agent-studio.example.com/api/vault \
  --header 'X-Organization-Id: org_example' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Support model key",
  "key": "SUPPORT_MODEL_KEY",
  "value": "example-secret-value",
  "category": "API_KEY",
  "description": "Credential used by the support workflow",
  "tags": [
    "support",
    "model"
  ],
  "organizationId": "org_example"
}'

{ "success": true, "data": { "id": "vault_example", "name": "Support model key", "key": "SUPPORT_MODEL_KEY", "category": "API_KEY" } }

Creating an organization entry requires membership and the vault:create permission.

Update a vault entry

curl --request PUT \
  --url https://agent-studio.example.com/api/vault \
  --header 'Content-Type: application/json' \
  --data '{
  "id": "vault_example",
  "name": "Rotated support model key",
  "key": "SUPPORT_MODEL_KEY",
  "value": "example-rotated-secret-value",
  "category": "API_KEY",
  "description": "Rotated credential used by the support workflow",
  "tags": [
    "support",
    "rotated"
  ]
}'

{ "success": true, "data": { "id": "vault_example", "key": "SUPPORT_MODEL_KEY" } }

The entry owner can update it. For an organization-owned entry belonging to another user, the current user must have the OWNER or ADMIN role.

Delete a vault entry

curl --request DELETE \
  --url https://agent-studio.example.com/api/vault?id=vault_example

{ "success": true }

The same owner-or-organization-administrator rule applies to deletion.

Reveal a vault value

curl --request GET \
  --url https://agent-studio.example.com/api/vault/vault_example/reveal

{ "success": true, "rawValue": "<secret-value>" }

Related operation families

The remaining administrative surfaces use separate permission and lifecycle rules. Use these references and guides before calling them:

Next steps