Manage organizations
Create, inspect, update, and safely delete a shared organization boundary through the Agent Studio API.
Create an organization, confirm its stored details, update its metadata, and remove it when it is no longer needed. Use this workflow when you need a shared tenant boundary for members and organization-owned resources.
Before you begin
You need an authenticated Agent Studio session and permission to perform the requested organization operation. The examples use https://agent-studio.example.com; replace it with your Agent Studio origin and replace <session-cookie> with the cookie from your configured authentication provider.
Choose a name of 2–100 characters. If you provide a slug, use only lowercase letters, digits, and hyphens. The slug is set at creation and is not accepted by the update route.
The organization ID returned at creation identifies the boundary in later API paths. Listing and inspection are non-destructive; updating changes metadata; deletion removes the boundary and cascades to several related organization records.
Manage the lifecycle
Send POST /api/organizations with the organization name and an optional slug and billing contact.
curl -X POST 'https://agent-studio.example.com/api/organizations' \
-H 'Content-Type: application/json' \
-H 'Cookie: __session=<session-cookie>' \
-d '{
"name": "Example Support",
"slug": "example-support",
"billingEmail": "billing@example.com"
}'A successful request returns 201 with success: true and the created organization in data.
Copy data.id from the creation response and use it in subsequent requests. This guide uses org_example as a placeholder; send the literal ID returned by your deployment.
{
"success": true,
"data": {
"id": "org_example",
"name": "Example Support",
"slug": "example-support",
"plan": "free"
}
}The ID remains the API identifier even when you later change the display name.
Send GET /api/organizations to confirm the organization is available to your account.
curl 'https://agent-studio.example.com/api/organizations' \
-H 'Cookie: __session=<session-cookie>'The data array contains the organizations returned for the current user. Find the entry whose id matches the value saved in the previous step.
Request the organization by ID before changing it.
curl 'https://agent-studio.example.com/api/organizations/org_example' \
-H 'Cookie: __session=<session-cookie>'The response returns the current organization in data, including its name, slug, plan, settings, and timestamps where present.
Send only the supported fields that you intend to change: name, billingEmail, or settings. Omitted fields remain outside the requested update.
curl -X PUT 'https://agent-studio.example.com/api/organizations/org_example' \
-H 'Content-Type: application/json' \
-H 'Cookie: __session=<session-cookie>' \
-d '{
"name": "Example Support Operations",
"settings": {"defaultCollection":"support"}
}'The response returns success: true and the updated organization in data. The route does not accept a replacement slug or plan.
Before deletion, inspect the organization and the administrative surfaces you use. An organization can own members, invitations, roles, API keys, skills, executions, MCP servers, vault entries, webhook triggers, cron schedules, audit logs, agent memories, and a budget policy.
Move, export, or otherwise preserve any information your operating procedures require. The organization endpoint does not provide a dry-run option or a dependency summary.
When you have confirmed the ID and no longer need the boundary, send the delete request.
curl -X DELETE 'https://agent-studio.example.com/api/organizations/org_example' \
-H 'Cookie: __session=<session-cookie>'A successful deletion returns { "success": true }. This action is destructive; do not use it as a cleanup test against shared or production data.
Verify the result
After creation or update, repeat GET /api/organizations/{id} and compare data.name, data.billingEmail, and data.settings with the values you submitted. After deletion, list organizations and confirm that the deleted ID is absent. Do not infer deletion from a client-side timeout; require a successful API response and a follow-up read.