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

The company’s timezone, an IANA name such as America/New_York (every company starts there). A deployment created without a timezone takes this one, and the studio says when a post goes out in it.

string | null

The company’s logo, an SVG (see The logo); null until one is set. The studio shows it in its top-left corner and in its apps.

object | null

The company’s brand kit (see The brand kit): { palette, typeface, tagline }; null until one is set. Whoever makes things in the company’s look reads it.

boolean

true while the company is being set up: made in a chat with its CEO and not yet activated by a paid plan. It turns false the first time the plan reads active and never back, even if the plan later lapses.

string | null

The blueprint/template a link named when the company was made (see Set up a company); null otherwise.

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.

Set up a company

POST /v1/organizations/setup → 201 Created, or 200 OK when it already exists The company a signed-in person is setting up, found or made. A person with no company starts here: the company is made unnamed (“New company”), live, with them as its owner, and it is set up in a chat with its CEO before it is paid for. A person has at most one company being set up, so asking again — another tab, a retry, the next sign-in — answers the same one. Once it is activated by a payment, the next call makes a new one. It mints no API key. An API key, or a call with no session, is refused with 403 or 401.

string

The blueprint/template a link named, such as media/faceless. Stored as start_template when the company is made; ignored when it already exists. Anything that is not two lower-case names joined by / is 400 validation_failed.

string

A creator’s referral code, as on create.

Response

{ "organization": { "id": "org_01H8AA...", "object": "organization", "name": "New company", "balance_micro_usd": 1000000, "timezone": "America/New_York", "logo_svg": null, "brand": null, "setting_up": true, "start_template": "media/faceless", "created_at": "2026-09-30T17:00:00Z" } }

Before it is activated, only its CEO chat runs, on the setup model, paid for by a one-time setup credit the company is given here. The credit is once per person: an address that is another spelling of one whose company is still being set up (a +tag, or Gmail’s dots) gets its company but no second credit. A person whose earlier company was activated is credited again. A company being set up cannot top up (402); its next step is the plan. A template set up in that chat is recorded as held and built when the company is activated (installs).

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, "timezone": "America/New_York", "logo_svg": null, "brand": null, "setting_up": false, "start_template": null, "created_at": "2026-08-20T17:00:00Z" }

Update an organization

PATCH /v1/organizations/{id}

string

New display name.

string

New timezone, an IANA name (America/Los_Angeles). It is stored under its canonical name (US/Eastern is kept as America/New_York). An abbreviation (EST), an offset (+05:00) or a name the platform does not know is 400 validation_failed on timezone. Only the fields you send are changed: a rename leaves the timezone as it is.

string | null

A new logo, as SVG text; null removes it. It is stored trimmed, with xmlns="http://www.w3.org/2000/svg" added to the root when it has none. A logo the rules below refuse is 400 validation_failed on logo_svg, and the message says what to change.

object | null

A new brand kit; null removes it. See The brand kit. A kit that does not match it exactly is 400 validation_failed on brand.

Send at least one of them. Only the fields you send are changed. Returns the updated organization object. A company being set up can be updated too: its CEO names it and sets its logo and brand kit before it is activated.

The logo

A logo is one <svg> element that the platform checks before it stores it. The check is an allow-list:

At most 16 KB, and exactly one root <svg> with a viewBox of four numbers. No nested <svg>.
Elements: svg, g, path, rect, circle, ellipse, line, polyline, polygon, defs, linearGradient, radialGradient, stop, title, desc, clipPath, mask. <title> and <desc> hold words only. Anything else is refused, including <text> (draw letters as paths), <image>, <use>, <style>, <script>, <a> and animation.
Attributes: geometry and presentation only (viewBox, xmlns, width, height, x…y2, cx, cy, r, rx, ry, d, points, fill, stroke and its stroke-* family, opacity, fill-opacity, fill-rule, clip-rule, transform, offset, stop-color, stop-opacity, gradientUnits, gradientTransform, id, clip-path, mask, preserveAspectRatio, fx, fy, spreadMethod, role, aria-hidden). Every value is quoted. No on… handlers, href, style or class.
A value holds numbers, names, #colours and url(#id) only: no other url(…), no javascript:, data: or http, no entities, and no <.
No comments, CDATA, DOCTYPE, entities or processing instructions.

An agent can set the logo too, with the company.set_logo tool. It passes the same check.

The brand kit

The company’s look, beside its logo: a palette, a typeface and a tagline.

object[]

3 to 6 colours, each { name, hex }: a name of 1–24 characters and a lower-case #rrggbb.

string

grotesk, serif, rounded or mono.

string

One line of up to 80 characters; "" for none.

{ "palette": [{ "name": "Ink", "hex": "#1b1f3a" }, { "name": "Tide", "hex": "#2f6fdf" }, { "name": "Foam", "hex": "#eef3fb" }], "typeface": "grotesk", "tagline": "Small-batch bread, daily." }

No other field is accepted. An agent sets it with company.set_brand, which builds the palette from one colour.

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

Set up a company

List, retrieve & update

Update an organization

The logo

The brand kit

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

​Set up a company

​List, retrieve & update

​Update an organization

​The logo

​The brand kit

​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

Set up a company

List, retrieve & update

Update an organization

The logo

The brand kit

Members

The member object

List members

Add a member

Update a member’s role

Remove a member

API keys