Organizations

An organization is the top-level container and billing entity. It holds the credit balance, owns every agent, computer, skill, and file, and has members (users with a role) and API keys (programmatic access). Every request is scoped to exactly one organization via its API key.

The organization object

string

Unique id (e.g. org_01H...).

string

Display name.

integer

Current credit balance, in micro-USD.

string

Creation timestamp.

Create an organization

POST /v1/organizations → 201 Created The only write that is not scoped to an organization — it is how an existing caller gets another one. Authenticate with either an admin API key or a signed-in user session; an unauthenticated call is refused with 401. Your first organization comes from signing up, not from this route.

string

required

Display name for the organization.

string

A creator’s referral code, accepted from a signed-in user session only. Attributes the new organization to that creator; a code that cannot be honoured is ignored and the organization is still created.

curl -fsSL https://api.vetta.sh/v1/organizations \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "name": "Acme" }'

Response

{
  "organization": { "id": "org_01H8AA...", "object": "organization", "name": "Acme", "balance_micro_usd": 0, "created_at": "2026-08-20T17:00:00Z" },
  "api_key": { "id": "key_01H8AB...", "object": "api_key", "name": "Acme", "prefix": "sk_live_9f2c", "scopes": ["admin"], "org_id": "org_01H8AA...", "mode": "live", "secret": "sk_live_9f2c...redacted", "created_at": "2026-08-20T17:00:00Z" }
}

The reply carries two objects: the organization and the first admin key that opens it, whose secret is returned here and never again. A caller signed in as a person also becomes the founding owner.

List, retrieve & update

GET   /v1/organizations         # list the orgs the caller belongs to
GET   /v1/organizations/{id}    # retrieve

GET /v1/organizations is orgless — it answers on a user session rather than an org-scoped key, which is what makes org switching possible. See Authentication.

Response

{ "id": "org_01H8AA...", "object": "organization", "name": "Acme", "balance_micro_usd": 48250000, "created_at": "2026-08-20T17:00:00Z" }

Update an organization

PATCH /v1/organizations/{id}

string

required

New display name.

Returns the updated organization object.

Members

Users belong to an organization with a role that controls what they can do.

Role	Can do
`owner`	Everything, including billing, members, and deleting the org.
`admin`	Manage agents, computers, skills, keys, and view billing.
`member`	Create and run agents within the org’s resources.

The member object

string

Member id (e.g. usr_01H...). It is the id the member routes address and the id the audit log records as the actor.

string

The member’s email address.

string

owner | admin | member.

string | null

Id of the member who invited them; null for the founding owner.

string

When the member joined the organization.

List members

GET /v1/organizations/{id}/members — cursor-paginated. See Pagination.

Response

{
  "data": [
    { "id": "usr_01H...", "email": "owner@acme.com", "role": "owner", "invited_by": null, "created_at": "2026-06-01T09:00:00Z" },
    { "id": "usr_01H...", "email": "alice@acme.com", "role": "admin", "invited_by": "usr_01H...", "created_at": "2026-08-20T17:00:00Z" }
  ],
  "has_more": false,
  "next_cursor": null
}

Add a member

POST /v1/organizations/{id}/members

string

required

Email address to invite.

string

required

owner | admin | member.

curl -fsSL https://api.vetta.sh/v1/organizations/org_01H8AA.../members \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "email": "alice@acme.com", "role": "admin" }'

Response

{ "id": "usr_01H9JJ...", "object": "member", "email": "alice@acme.com", "role": "admin", "invited_by": "usr_01H...", "created_at": "2026-08-20T17:00:00Z" }

Update a member’s role

PATCH /v1/organizations/{id}/members/{member_id}

string

required

owner | admin | member.

Remove a member

DELETE /v1/organizations/{id}/members/{member_id} Both mutations are recorded in the audit log as member.role_changed and member.removed, attributed to the acting principal.

Removal does not cascade. It deletes the membership row and nothing else. API keys that member created keep working and sessions running under them keep running — revoke each one you want stopped with DELETE /v1/api_keys/{id}, reading GET /v1/api_keys first, because a key’s created_by is the only record of who minted it. Agents, skills and files are org-owned and remain. Re-inviting the same email creates a new member.

API keys

Programmatic access uses org-scoped API keys, managed under /v1/api_keys. For creation, scopes, and rotation, see Authentication.

POST   /v1/api_keys              # create
GET    /v1/api_keys              # list (cursor-paginated)
POST   /v1/api_keys/{id}/rotate  # rotate
DELETE /v1/api_keys/{id}         # revoke

Only owner and admin members (or a key with the admin scope) can manage members and API keys.

Credits & billing

The org’s real-USD balance, ledger, and top-ups.

Introduction

Core resources

Platform

Identity

Organizations

The organization object

Create an organization

List, retrieve & update

Update an organization

Members

The member object

List members

Add a member

Update a member’s role

Remove a member

API keys

Credits & billing

​The organization object

​Create an organization

​List, retrieve & update

​Update an organization

​Members

​The member object

​List members

​Add a member

​Update a member’s role

​Remove a member

​API keys

Credits & billing

The organization object

Create an organization

List, retrieve & update

Update an organization

Members

The member object

List members

Add a member

Update a member’s role

Remove a member

API keys