Reference

API reference

Updated October 5, 2026

Everything the web app does goes through the same HTTP API, and you can call it too. The reference below is generated from the API's own OpenAPI document every time the site is built, so it lists exactly the routes the API serves.

Base address

Every route lives under /v1 on the API's origin, for example https://api.useyard.app/v1/health (a self-hosted Yard uses its own PUBLIC_API_URL). Requests and answers are JSON.

Authenticating

From a script or another service, use an API key in the Authorization header:

curl -H "Authorization: Bearer $YARD_API_KEY" https://api.useyard.app/v1/orgs

Personal keys (yard_pk_…) act as you, with the role you have now in each organization. Create them in Account → API keys.
Organization keys (yard_ok_…) act for one organization only, with at most the role they were created with. Organization admins create them in Settings → API keys.

A key is shown once when it is created; only a hash is stored. Keys can expire, be rotated (the old secret keeps working for a grace period) and be revoked. The yard CLI gets its own key when you run yard login.

Scopes

Scope	Allows
`read`	`GET` requests.
`write`	Every other method.
`runners`	Managing runners (`/v1/orgs/{org}/runners`).
`admin`	Instance administration (`/v1/admin`); only on an instance admin's personal key.

Some things can never be done with a key, whatever its scopes: managing keys, sessions, passwords, passkeys and two-step sign-in, agent sign-ins, connecting GitHub and approving a CLI sign-in. Sign in to the app for those. An organization key also cannot reach a person's own settings.

Limits

Each key may make 600 requests a minute. Over that the API answers 429.

Errors

A failed request answers with a status and a JSON body with a human-readable error and a stable code, for example {"error": "This API key needs the \write` scope for this.", "code": "key_scope"}`.

401: not signed in, or the key is unknown, revoked or expired.
403: signed in, but not allowed (a missing scope, a role too low).
404: not found, also when something exists in an organization you cannot see.

Health

GET `/v1/health`

Liveness and version

200 The API is up: Health

Auth

POST `/v1/auth/signout`

End the current session

200 OK: Ok

GET `/v1/auth/me`

The signed-in user and their organizations

200 OK: Me

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/auth/me`

Update the profile

Request body: UpdateProfileBody

200 OK: UserResponse

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/verify`

Verify the email with the 6-digit code

Request body: VerifyBody

200 OK: UserResponse

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/verify/resend`

Send a new verification code

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/auth/password`

Change the password

Request body: ChangePasswordBody

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/auth/providers`

Ways to sign in besides a password

200 OK: AuthProviders

POST `/v1/auth/github/url`

Where to send the browser to sign in with GitHub

Request body: GithubSigninBody

200 OK: InstallUrl

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/auth/github/signup`

What GitHub said about someone signing up through it

Query parameters

Name	Type	Description
`ticket`	`string`

200 OK: GithubSignupPending

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/2fa/totp/setup`

Start adding an authenticator app

200 OK: TotpSetup

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/2fa/totp/enable`

Confirm the authenticator app with a code; returns recovery codes once

Request body: TotpCodeBody

200 OK: RecoveryCodes

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/2fa/totp/disable`

Stop asking for authenticator codes

Request body: TotpCodeBody

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/2fa/verify`

Finish signing in with an authenticator, email or recovery code

Request body: TwoFactorVerifyBody

200 OK: UserResponse

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/2fa/email/send`

Mail a sign-in code for a half-done sign-in

Request body: TwoFactorEmailSendBody

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/2fa/email/setup`

Start using email codes: mails a code to confirm

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/2fa/email/enable`

Confirm email codes with the mailed code

Request body: TotpCodeBody

200 OK: UserResponse

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/2fa/email/disable`

Stop asking for email codes; needs the password

Request body: EmailFactorDisableBody

200 OK: UserResponse

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/auth/2fa/preferred`

Choose the second step sign-in starts with

Request body: TwoFactorPreferredBody

200 OK: UserResponse

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/auth/passkeys`

The caller's passkeys

200 OK

Name	Type	Description
`passkeys`	`Passkey[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/passkeys/register/options`

Options for creating a passkey

200 OK: object

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/auth/passkeys/register/verify`

Save a new passkey

Request body: PasskeyRegisterBody

200 OK: Passkey

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/auth/passkeys/{id}`

Remove a passkey

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

Orgs

GET `/v1/orgs`

Organizations the caller belongs to

200 OK

Name	Type	Description
`orgs`	`Org[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs`

Create an organization

Request body: CreateOrgBody

200 OK: Org

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}`

One organization

Path parameters

Name	Type	Description
`org`	`string`	Organization id or slug

200 OK: Org

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/orgs/{org}`

Update organization settings

Path parameters

Name	Type	Description
`org`	`string`	Organization id or slug

Request body: UpdateOrgBody

200 OK: Org

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}`

Delete an organization

Path parameters

Name	Type	Description
`org`	`string`	Organization id or slug

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/members`

Members of an organization

Path parameters

Name	Type	Description
`org`	`string`	Organization id or slug

200 OK

Name	Type	Description
`members`	`Member[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/orgs/{org}/members/{userId}`

Change a member's role

Path parameters

Name	Type	Description
`org`	`string`	Organization id or slug
`userId`	`string`

Request body: UpdateMemberBody

200 OK: Member

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/members/{userId}`

Remove a member, or leave

Path parameters

Name	Type	Description
`org`	`string`	Organization id or slug
`userId`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

API keys

GET `/v1/me/api-keys`

The caller's personal API keys

200 OK

Name	Type	Description
`keys`	`ApiKey[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/api-keys`

Create a personal API key; the secret is shown once

Request body: CreateApiKeyBody

200 OK: CreatedApiKey

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/me/api-keys/{id}`

Revoke a personal API key

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/api-keys/{id}/rotate`

Give a personal API key a new secret; the old one works for a grace period

Path parameters

Name	Type	Description
`id`	`string`

Request body: RotateApiKeyBody

200 OK: CreatedApiKey

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/api-keys`

The organization's API keys (org admins)

Path parameters

Name	Type	Description
`org`	`string`

200 OK

Name	Type	Description
`keys`	`ApiKey[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/api-keys`

Create an organization API key (org admins); the secret is shown once

Path parameters

Name	Type	Description
`org`	`string`

Request body: CreateApiKeyBody

200 OK: CreatedApiKey

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/api-keys/{id}`

Revoke an organization API key (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/api-keys/{id}/rotate`

Give an organization API key a new secret (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

Request body: RotateApiKeyBody

200 OK: CreatedApiKey

Errors: 400, 401, 403, 404, 409, 429 with an error body

CLI sign-in

POST `/v1/cli/login/poll`

Whether the person confirmed the code; the key, once

Request body

Name	Type	Description
`deviceToken`	`string`

200 OK: CliLoginPoll

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/cli/login/{code}/approve`

Confirm a CLI sign-in: mints a personal key for that CLI

Path parameters

Name	Type	Description
`code`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/cli/logout`

Revoke the API key this request is made with (yard logout)

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

Invites

GET `/v1/orgs/{org}/invites`

Pending invites

Path parameters

Name	Type	Description
`org`	`string`

200 OK

Name	Type	Description
`invites`	`Invite[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/invites`

Invite by email, or create a shareable link

Path parameters

Name	Type	Description
`org`	`string`

Request body: CreateInviteBody

200 OK: CreatedInvite

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/invites/{id}`

Revoke an invite

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/invites/{token}`

What an invite link grants (public)

Path parameters

Name	Type	Description
`token`	`string`

200 OK: InvitePreview

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/invites/{token}/accept`

Join the organization

Path parameters

Name	Type	Description
`token`	`string`

200 OK: AcceptedInvite

Errors: 400, 401, 403, 404, 409, 429 with an error body

Runners

GET `/v1/orgs/{org}/runners`

Runners this organization can use

Path parameters

Name	Type	Description
`org`	`string`

200 OK

Name	Type	Description
`runners`	`Runner[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/runners`

Path parameters

Name	Type	Description
`org`	`string`

Request body: CreateRunnerBody

200 OK: CreatedRunner

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/orgs/{org}/runners/{id}`

Change how many agent turns an organization's runner runs at once, and when they wait for its load (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

Request body: UpdateRunnerBody

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/runners/{id}`

Remove an organization's runner

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/runners/{id}/rotate-token`

Give an organization's runner a new token; the old one stops working

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: RotatedRunnerToken

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/runners/{id}/rotate-token`

Give an official runner a new token (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: RotatedRunnerToken

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/runners/{id}/device/approve`

Pin the runner to the machine it connected from instead (org admins); a waiting connection goes live

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/runners/{id}/device/approve`

Pin the runner to the machine it connected from instead (instance admins); a waiting connection goes live

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/runners/{id}/device/reject`

Refuse the other machine (org admins); its connection is closed

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/runners/{id}/device/reject`

Refuse the other machine (instance admins); its connection is closed

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/runners/{id}/device/reset`

Forget the runner's machine (org admins); the next connection is pinned on trust

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/runners/{id}/device/reset`

Forget the runner's machine (instance admins); the next connection is pinned on trust

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/orgs/{org}/runners/{id}/direct`

Give a pinned runner its own https address for terminals and downloads (org admins); checked at once

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

Request body: SetRunnerDirectBody

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/runners/{id}/direct`

Stop using the runner's own address (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/runners/{id}/direct/verify`

Check now that the runner's address answers as this runner (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/me/runners`

The caller's personal runners

200 OK

Name	Type	Description
`runners`	`Runner[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/runners`

Request body: CreateRunnerBody

200 OK: CreatedRunner

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/me/runners/{id}`

Change a personal runner: whether others may edit the workspaces on it (they can always view them), and how many agent turns it runs at once

Path parameters

Name	Type	Description
`id`	`string`

Request body: UpdatePersonalRunnerBody

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/me/runners/{id}`

Remove a personal runner

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/runners/{id}/rotate-token`

Give a personal runner a new token; the old one stops working

Path parameters

Name	Type	Description
`id`	`string`

200 OK: RotatedRunnerToken

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/runners/{id}/device/approve`

Pin the personal runner to the machine it connected from instead

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/runners/{id}/device/reject`

Refuse the other machine; its connection is closed

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/runners/{id}/device/reset`

Forget the runner's machine; the next connection is pinned on trust

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/me/runners/{id}/direct`

Give a pinned personal runner its own https address; checked at once

Path parameters

Name	Type	Description
`id`	`string`

Request body: SetRunnerDirectBody

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/me/runners/{id}/direct`

Stop using the personal runner's own address

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/runners/{id}/direct/verify`

Check now that the personal runner's address answers as this runner

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/admin/runners/{id}`

Change how many agent turns any runner runs at once, and when they wait for its load (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

Request body: UpdateRunnerBody

200 OK: Runner

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/runners/{id}/queue`

What runs and waits on an organization's runner, and what failed (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: RunnerQueue

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/runners/{id}/queue`

What runs and waits on any runner, and what failed (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: RunnerQueue

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/me/runners/{id}/queue`

What runs and waits on a personal runner, and what failed

Path parameters

Name	Type	Description
`id`	`string`

200 OK: RunnerQueue

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/runner-queue`

This workspace's turns on its runner, and how busy the runner is (read only)

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: RunnerQueue

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/runners/{id}/retry-failed`

Queue every failed project and chat on an organization's runner again (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

Request body: RetryFailedBody

200 OK: RetryFailedResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/runners/{id}/retry-failed`

Queue every failed project and chat on any runner again (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

Request body: RetryFailedBody

200 OK: RetryFailedResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/me/runners/{id}/retry-failed`

Queue every failed project and chat on a personal runner again

Path parameters

Name	Type	Description
`id`	`string`

Request body: RetryFailedBody

200 OK: RetryFailedResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/retry-failed`

Queue every failed project and chat of this workspace again

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: RetryFailedResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/runners/{id}/update`

Have an online organization runner install the newest build and restart (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: RunnerUpdateStarted

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/runners/{id}/update`

Have any online runner install the newest build and restart (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: RunnerUpdateStarted

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/runners`

Request body

Name	Type	Description
`name`	`string`
`tier`optional	`"standard" \| "pro"`

200 OK: CreatedRunner

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/runner/releases`

Downloadable runner builds (public)

200 OK: RunnerReleases

Errors: 400, 401, 403, 404, 409, 429 with an error body

Instance admins

GET `/v1/admin/runners`

Every runner, official and organizations' (instance admins)

200 OK

Name	Type	Description
`runners`	`AdminRunner[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/claim`

Whether the instance has an admin yet, and how the first one claims it

200 OK: AdminClaimState

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/claim`

Become the first instance admin with the code from the console

Request body

Name	Type	Description
`code`optional	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/claim/request`

Print a one-time claim code to the API's console

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/overview`

Counts across the instance (instance admins)

200 OK: AdminOverview

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/orgs`

Every organization, with counts (instance admins)

200 OK

Name	Type	Description
`orgs`	`AdminOrg[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/users`

People on this instance (instance admins)

Query parameters

Name	Type	Description
`q`optional	`string`

200 OK

Name	Type	Description
`users`	`AdminUser[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/admin/users/{id}`

Make someone an admin or not (the owner), disable or enable them (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

Request body: UpdateAdminUserBody

200 OK: AdminUser

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/admin/users/{id}/sessions`

Sign someone out everywhere and revoke their API keys (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/usage/ai`

Agent turns, tokens and cost (instance admins)

Query parameters

Name	Type	Description
`groupBy`optional	`"org" \| "user" \| "provider" \| "model" \| "day"`
`days`optional	`integer`

200 OK

Name	Type	Description
`rows`	`AiUsageRow[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/admin/feedback/{id}`

Mark feedback seen or done, or archive it (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

Request body

Name	Type	Description
`status`optional	`"new" \| "seen" \| "done"`
`archived`optional	`boolean`

200 OK

Name	Type	Description
`id`	`string`
`status`	`"new" \| "seen" \| "done"`
`archivedAt`	`string \| null`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/email`

Recent emails and failures (instance admins)

200 OK

Name	Type	Description
`transport`	`string`
`delivers`	`boolean`
`emails`	`EmailEvent[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/email/test`

Send a test email to yourself (instance admins)

200 OK: EmailEvent & object | null

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/audit`

What instance admins did (instance admins)

200 OK

Name	Type	Description
`events`	`AuditEvent[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/system`

Version and which settings are configured (instance admins)

200 OK: AdminSystem

Errors: 400, 401, 403, 404, 409, 429 with an error body

Hosters

GET `/v1/orgs/{org}/hosters`

Hosters this organization can use: its own and the official ones

Path parameters

Name	Type	Description
`org`	`string`

200 OK

Name	Type	Description
`hosters`	`Hoster[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/hosters`

Path parameters

Name	Type	Description
`org`	`string`

Request body: CreateRunnerBody

200 OK: CreatedHoster

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/hosters/{id}`

Remove an organization's hoster (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/hosters/{id}/rotate-token`

Give a hoster a new token; the old one stops working (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: CreatedHoster

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/hosters/{id}/reset-device`

Forget the hoster's machine; the next one to connect is pinned (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Hoster

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/hosters`

Every hoster, official and organizations' (instance admins)

200 OK

Name	Type	Description
`hosters`	`object[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/hosters`

Request body: CreateOfficialHosterBody

200 OK: CreatedHoster

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/hosters/{id}/rotate-token`

Give an official hoster a new token; the old one stops working (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: CreatedHoster

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/hosters/{id}/reset-device`

Forget an official hoster's machine; the next one to connect is pinned (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Hoster

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/admin/hosters/{id}`

Remove an official hoster (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

Storage

GET `/v1/orgs/{org}/storage`

Where this organization's files are stored

Path parameters

Name	Type	Description
`org`	`string`

200 OK: OrgStorage

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/orgs/{org}/storage`

Set the organization's bucket

Path parameters

Name	Type	Description
`org`	`string`

Request body: UpdateOrgStorageBody

200 OK: OrgStorage

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/storage/test`

Write, read and delete a probe object

Path parameters

Name	Type	Description
`org`	`string`

200 OK: StorageTestResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/storage/buckets`

The host's buckets (instance admins)

200 OK

Name	Type	Description
`buckets`	`StorageBucket[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/storage/buckets`

Add a bucket every organization can use (instance admins)

Request body: CreateStorageBucketBody

200 OK: StorageBucket

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/admin/storage/buckets/{id}`

Rename, make default, stop new workspaces or change keys (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

Request body: UpdateStorageBucketBody

200 OK: StorageBucket

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/admin/storage/buckets/{id}`

Remove a host bucket no workspace uses (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/admin/storage/buckets/{id}/test`

Write, read and delete a probe object (instance admins)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: StorageTestResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/storage/buckets`

Buckets this organization's workspaces can use

Path parameters

Name	Type	Description
`org`	`string`

200 OK

Name	Type	Description
`buckets`	`StorageBucket[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/storage/buckets`

Add a bucket of the organization's own (org admins)

Path parameters

Name	Type	Description
`org`	`string`

Request body: CreateStorageBucketBody

200 OK: StorageBucket

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/orgs/{org}/storage/buckets/{id}`

Change one of the organization's buckets (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

Request body: UpdateStorageBucketBody

200 OK: StorageBucket

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/storage/buckets/{id}`

Remove one of the organization's buckets no workspace uses (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/storage/buckets/{id}/test`

Write, read and delete a probe object (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: StorageTestResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/storage`

Which bucket this workspace's files are in, and any move under way

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: WorkspaceStorage

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/storage/migrate`

Move this workspace's files to another bucket (org admins)

Path parameters

Name	Type	Description
`ws`	`string`

Request body

Name	Type	Description
`bucketId`	`string`

200 OK: WorkspaceStorage

Errors: 400, 401, 403, 404, 409, 429 with an error body

Integrations

GET `/v1/me/integrations`

Outside services you connected, and the ones you can

200 OK: IntegrationList

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/me/integrations/{provider}`

Connect a service with your own key (checked with the service first)

Path parameters

Name	Type	Description
`provider`	`IntegrationProvider`

Request body: ConnectIntegrationBody

200 OK: Integration

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/me/integrations/{provider}`

Forget your key for a service

Path parameters

Name	Type	Description
`provider`	`IntegrationProvider`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/integrations`

Services the organization connected for its members

Path parameters

Name	Type	Description
`org`	`string`

200 OK: IntegrationList

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/orgs/{org}/integrations/{provider}`

Connect a service for everyone in the organization (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`provider`	`IntegrationProvider`

Request body: ConnectIntegrationBody

200 OK: Integration

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/integrations/{provider}`

Forget the organization's key for a service (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`provider`	`IntegrationProvider`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/stt/status`

Whether dictation can use server speech to text, with your key or the organization's

Query parameters

Name	Type	Description
`org`optional	`string`

200 OK: SttStatus

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/stt/transcribe`

Turn a recording into text with Mistral

Request body: TranscribeBody

200 OK: Transcription

Errors: 400, 401, 403, 404, 409, 429 with an error body

Workspaces

GET `/v1/orgs/{org}/workspaces`

Workspaces the caller can open

Path parameters

Name	Type	Description
`org`	`string`

Query parameters

Name	Type	Description
`archived`optional	`"true" \| "false"`

200 OK

Name	Type	Description
`workspaces`	`Workspace[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/workspaces`

Create a workspace on a runner

Path parameters

Name	Type	Description
`org`	`string`

Request body: CreateWorkspaceBody

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/workspaces/{slug}`

One workspace, by its URL slug

Path parameters

Name	Type	Description
`org`	`string`
`slug`	`string`

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}`

One workspace

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/workspaces/{ws}`

Update workspace settings, or move it to another runner

Path parameters

Name	Type	Description
`ws`	`string`

Request body: UpdateWorkspaceBody

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/workspaces/{ws}`

Delete an archived workspace

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/workspaces/{ws}/logo`

Set the workspace's logo

Path parameters

Name	Type	Description
`ws`	`string`

Request body: SetWorkspaceLogoBody

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/workspaces/{ws}/logo`

Remove the workspace's logo (its initials show)

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/retry`

Retry provisioning after a failure

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/unarchive`

Bring an archived workspace back onto a runner

Path parameters

Name	Type	Description
`ws`	`string`

Request body: UnarchiveBody

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/archive`

Stop the runtime; files stay in storage for the retention period

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: Workspace

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/workspaces/{ws}/share/members/{userId}`

Grant, change or clear one person's role

Path parameters

Name	Type	Description
`ws`	`string`
`userId`	`string`

Request body: SetShareRoleBody

200 OK: Share

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/share/invite`

Share with someone by email

Path parameters

Name	Type	Description
`ws`	`string`

Request body: ShareInviteBody

200 OK: ShareInviteResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

Workspace content

GET `/v1/workspaces/{ws}/history`

Canvas history and unsaved changes

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`container`optional	`string`

200 OK: History

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/history/save`

Commit unsaved canvas changes now

Path parameters

Name	Type	Description
`ws`	`string`

Request body: SaveHistoryBody

200 OK: HistoryResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/history/{sha}/revert`

Put the canvas back to how it was at a commit

Path parameters

Name	Type	Description
`ws`	`string`
`sha`	`string`

Request body

Name	Type	Description
`container`optional	`string`

200 OK: HistoryResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/uploads`

Start an upload

Path parameters

Name	Type	Description
`ws`	`string`

Request body: CreateUploadBody

200 OK: UploadTicket

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/uploads/{id}/complete`

Bring an uploaded file into the workspace

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

200 OK: UploadResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/usage`

What the workspace's containers use right now, and its disk

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: WorkspaceUsage

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/usage`

What every workspace of the organization uses right now (admins)

Path parameters

Name	Type	Description
`org`	`string`

200 OK: OrgUsage

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/processes`

Processes running in the workspace's container, or in a project's

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`container`optional	`string`

200 OK: ProcessList

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/containers/stop-runtime`

Stop every container of the workspace; each starts again when it is next used

Path parameters

Name	Type	Description
`ws`	`string`

200 OK

Name	Type	Description
`stopped`	`integer`
`skipped`	`integer`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/processes/kill`

Stop one process in a container

Path parameters

Name	Type	Description
`ws`	`string`

Request body: KillProcessBody

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/link-preview`

Title, description and image of a web page, read from inside the workspace's box

Path parameters

Name	Type	Description
`ws`	`string`

Request body: LinkPreviewBody

200 OK: LinkPreview

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/snapshot`

Read-only copy of the canvas from storage, for when the runner is offline

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`container`optional	`string`

200 OK: SnapshotLink

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/terminals`

Open terminals

Path parameters

Name	Type	Description
`ws`	`string`

200 OK

Name	Type	Description
`terminals`	`Terminal[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/terminals`

Open a terminal in the workspace or one of its containers

Path parameters

Name	Type	Description
`ws`	`string`

Request body: CreateTerminalBody

200 OK: Terminal

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/workspaces/{ws}/terminals/{id}`

Close a terminal

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

Sheets

GET `/v1/workspaces/{ws}/sheets`

The sheets of the workspace canvas the caller may open, the first one first

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: SheetList

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/sheets`

Add a sheet to the workspace canvas

Path parameters

Name	Type	Description
`ws`	`string`

Request body: CreateSheetBody

200 OK: Sheet

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/sheets/{id}`

Rename a sheet, move it, or change who may open it

Path parameters

Name	Type	Description
`id`	`string`

Request body: UpdateSheetBody

200 OK: Sheet

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/sheets/{id}`

Delete a sheet (its files are archived in the workspace's history)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/sheets/{id}/members`

Who is on a sheet's list

Path parameters

Name	Type	Description
`id`	`string`

200 OK: SheetMembers

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/sheets/{id}/members/{user}`

Put someone on a sheet's list, or change their role there

Path parameters

Name	Type	Description
`id`	`string`
`user`	`string`

Request body: SetSheetMemberBody

200 OK: SheetMembers

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/sheets/{id}/members/{user}`

Take someone off a sheet's list

Path parameters

Name	Type	Description
`id`	`string`
`user`	`string`

200 OK: SheetMembers

Errors: 400, 401, 403, 404, 409, 429 with an error body

GitHub

GET `/v1/orgs/{org}/github`

GitHub App installations and the caller's GitHub connection

Path parameters

Name	Type	Description
`org`	`string`

200 OK: OrgGithub

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/github/install-url`

Where to send the browser to install the GitHub App

Path parameters

Name	Type	Description
`org`	`string`

Query parameters

Name	Type	Description
`next`optional	`string`

200 OK: InstallUrl

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/github/installations/{id}`

Forget an installation

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/github/connect-url`

Where to send the browser to connect a GitHub account

Request body

Name	Type	Description
`next`optional	`string`

200 OK: InstallUrl

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/github/me`

The caller's GitHub connection

200 OK: GithubIdentity

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/github/me`

Disconnect GitHub, and remove the repositories only its token could read

200 OK: GithubDisconnectResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/github/me/disconnect-preview`

Repositories that disconnecting GitHub removes

200 OK: GithubDisconnectPreview

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/github/pat`

Connect with a personal access token

Request body: SetPatBody

200 OK: GithubIdentity

Errors: 400, 401, 403, 404, 409, 429 with an error body

Repositories

GET `/v1/orgs/{org}/github/repos`

GitHub repositories the caller can connect

Path parameters

Name	Type	Description
`org`	`string`

Query parameters

Name	Type	Description
`q`optional	`string`

200 OK

Name	Type	Description
`repos`	`GithubRepo[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/repos`

Repositories connected to the organization

Path parameters

Name	Type	Description
`org`	`string`

200 OK

Name	Type	Description
`repos`	`Repo[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/repos`

Connect a GitHub repository

Path parameters

Name	Type	Description
`org`	`string`

Request body: ConnectRepoBody

200 OK: Repo

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/orgs/{org}/repos/new`

Create a repository on GitHub and connect it

Path parameters

Name	Type	Description
`org`	`string`

Request body: CreateRepoBody

200 OK: Repo

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/repos/{id}`

Disconnect a repository

Path parameters

Name	Type	Description
`org`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/repos`

Repositories mounted in a workspace

Path parameters

Name	Type	Description
`ws`	`string`

200 OK

Name	Type	Description
`repos`	`WorkspaceRepo[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/repos`

Mount a repository in a workspace

Path parameters

Name	Type	Description
`ws`	`string`

Request body: MountRepoBody

200 OK: WorkspaceRepo

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/repos/{id}/fetch`

Fetch the latest commits

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

200 OK: WorkspaceRepo

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/repos/{id}/branches`

Branches of a mounted repository

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

200 OK: RepoBranches

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/workspaces/{ws}/repos/{id}/branch`

Read the repository at another branch, and start projects from it

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

Request body: SetRepoBranchBody

200 OK: WorkspaceRepo

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/github/peek`

What a GitHub address of a mounted repository is about (for link cards)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`url`	`string`

200 OK: GithubPeek

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/workspaces/{ws}/repos/{id}/read-only`

Mark a repository read-only in this workspace (a reference), or allow edits again

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

Request body: SetRepoReadOnlyBody

200 OK: WorkspaceRepo

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/workspaces/{ws}/repos/{id}`

Remove a repository from a workspace

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

Files and git

GET `/v1/workspaces/{ws}/fs/files`

Files under a root (tracked and untracked, ignoring .gitignore'd ones)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK: FileList

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/fs/file`

Read a text file

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`
`path`	`string`

200 OK: FileContent

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/workspaces/{ws}/fs/file`

Write a text file (merged with changes made since `base`, when given)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`
`path`	`string`

Request body: WriteFileBody

200 OK: WriteFileResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/fs/transfer`

Copy or move a file or directory between roots (a task and the workspace)

Path parameters

Name	Type	Description
`ws`	`string`

Request body: TransferBody

200 OK: TransferResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/fs/remove`

Delete files and folders under a root

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

Request body: RemovePathsBody

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/fs/grep`

Search file contents

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`
`q`	`string`

200 OK: GrepResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/git/status`

Branch, head and uncommitted changes

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK: GitStatus

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/git/commits`

Commits on this branch

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`
`base`optional	`string`

200 OK

Name	Type	Description
`commits`	`GitCommit[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/git/diff-files`

Changed files for a diff target

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`
`target`	`string`

200 OK

Name	Type	Description
`files`	`GitFileChange[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/git/diff`

Unified diff

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`
`target`	`string`
`path`optional	`string`

200 OK: GitDiff

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/commit`

Commit everything, as the caller

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

Request body: CommitBody

200 OK

Name	Type	Description
`sha`	`string \| null`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/discard`

Discard uncommitted changes

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

Request body: DiscardBody

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/push`

Push the branch with the caller's GitHub token

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK

Name	Type	Description
`branch`	`string`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/fetch`

Fetch origin for a worktree: its counts against the base are current afterwards

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK: GitStatus

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/pull`

Fetch, then fast-forward the branch to its upstream (a diverged branch is refused, unchanged)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK: GitPullResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/update`

Merge the base branch into the worktree's branch, as the caller (aborted on a conflict)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK: GitUpdateResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/abort`

Abort the merge or rebase left half done in a worktree

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK: GitAbortResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/git/conflicts`

What merging the base into the worktree's branch would conflict on (nothing is changed)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK: GitConflicts

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/git/pr`

The pull request for this branch, if any

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

200 OK: PullRequestState

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/pr`

Open a pull request as the caller

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

Request body: OpenPrBody

200 OK: PullRequest

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/git/pr/merge`

Merge the pull request as the caller

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`scope`	`"workspace" \| "container" \| "worktree" \| "repo"`
`container`optional	`string`
`repo`optional	`string`

Request body: MergePrBody

200 OK: PullRequest

Errors: 400, 401, 403, 404, 409, 429 with an error body

Agent accounts

GET `/v1/agent/catalog`

Agents that can be connected, with their models

200 OK

Name	Type	Description
`agents`	`object[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/agent-accounts`

The caller's agent accounts

200 OK

Name	Type	Description
`accounts`	`AgentAccount[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/agent-accounts`

Add an agent account (then sign it in)

Request body: CreateAgentAccountBody

200 OK: AgentAccount

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/agent-accounts/{id}`

Remove an agent account and its stored credentials

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/agent-accounts/{id}/active`

Use this account for its agent's turns

Path parameters

Name	Type	Description
`id`	`string`

200 OK: AgentAccount

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/agent-accounts/{id}/workspaces/{ws}`

Pin this account to a workspace: it runs only there

Path parameters

Name	Type	Description
`id`	`string`
`ws`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/agent-accounts/{id}/workspaces/{ws}`

Unpin this account from a workspace

Path parameters

Name	Type	Description
`id`	`string`
`ws`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/agent-accounts/{id}/login`

Start signing in (runs the agent's own login on a runner)

Path parameters

Name	Type	Description
`id`	`string`

Request body: StartAgentLoginBody

200 OK: AgentLoginState

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/agent-accounts/{id}/login/code`

Submit the code the provider showed

Path parameters

Name	Type	Description
`id`	`string`

Request body: AgentLoginCodeBody

200 OK: AgentLoginState

Errors: 400, 401, 403, 404, 409, 429 with an error body

Chat

GET `/v1/workspaces/{ws}/chat`

Your own chat in the workspace, or in one of its projects (made when you have none)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`container`optional	`string`

200 OK: Chat

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/chats`

Everyone's chats in the workspace, or in one of its projects

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`container`optional	`string`

200 OK

Name	Type	Description
`chats`	`ChatSummary[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/chats`

Start another chat of your own in the workspace, or in one of its projects: a new tab

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`container`optional	`string`

200 OK: Chat

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/chats/{id}`

A chat: recent messages, what is queued, and the turn in progress

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Chat

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/chats/{id}`

Close a chat of your own: its tab goes away, its messages are kept

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/chats/{id}/clear`

Clear a chat of your own: it is closed and an empty one takes its place, so the agent starts fresh

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Chat

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/chats/{id}/messages`

Older messages

Path parameters

Name	Type	Description
`id`	`string`

Query parameters

Name	Type	Description
`before`	`integer`

200 OK

Name	Type	Description
`messages`	`ChatMessage[]`
`hasMore`	`boolean`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/chats/{id}/messages`

Send a message to the agent (queued if it is busy)

Path parameters

Name	Type	Description
`id`	`string`

Request body: SendChatBody

200 OK: ChatQueueItem

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/chats/{id}/fork`

Write into someone else's chat: starts a chat of your own that quotes theirs, and sends the message there

Path parameters

Name	Type	Description
`id`	`string`

Request body: SendChatBody

200 OK

Name	Type	Description
`chat`	`Chat`
`item`	`ChatQueueItem`

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/chats/{id}/queue/{item}`

Take back a message that has not started

Path parameters

Name	Type	Description
`id`	`string`
`item`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/chats/{id}/cancel`

Stop the running turn

Path parameters

Name	Type	Description
`id`	`string`

200 OK

Name	Type	Description
`stopped`	`boolean`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/chats/{id}/start-now`

Start the turn that waits in the runner's queue now, over the runner's limit (on an official runner: instance admins only). While it waits for the runner's load, only with `confirmLoad=true` (the person saw the warning); otherwise 409 `runner_overloaded`.

Path parameters

Name	Type	Description
`id`	`string`

Query parameters

Name	Type	Description
`confirmLoad`optional	`"true" \| "false"`

200 OK

Name	Type	Description
`started`	`boolean`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/chats/{id}/retry`

Send again what the chat's last turn was asked, after it ended in an error; it carries on from the conversation so far

Path parameters

Name	Type	Description
`id`	`string`

200 OK: ChatQueueItem

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/chats/{id}/resume-usage`

Usage is available again for the agent account holding this chat's messages: they, and the account's other held messages, go back into the queue

Path parameters

Name	Type	Description
`id`	`string`

200 OK

Name	Type	Description
`chats`	`integer`

Errors: 400, 401, 403, 404, 409, 429 with an error body

Containers

GET `/v1/workspaces/{ws}/containers`

Containers in a workspace (open ones, or the closed ones with closed=true)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`closed`optional	`"true" \| "false"`

200 OK

Name	Type	Description
`containers`	`Container[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/containers`

Create a container from instructions, selected blocks and repositories

Path parameters

Name	Type	Description
`ws`	`string`

Request body: CreateContainerBody

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/containers/purge-closed`

Delete every closed container of the workspace for good

Path parameters

Name	Type	Description
`ws`	`string`

200 OK

Name	Type	Description
`deleted`	`integer`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/containers/by-slug/{slug}`

A container by its directory name

Path parameters

Name	Type	Description
`ws`	`string`
`slug`	`string`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/chat-logs`

What the chat-log blocks show, including for deleted containers

Path parameters

Name	Type	Description
`ws`	`string`

200 OK

Name	Type	Description
`logs`	`object[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/containers/{id}`

A container, with fresh branch state when its runner is online

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/containers/{id}`

Rename a container

Path parameters

Name	Type	Description
`id`	`string`

Request body: UpdateContainerBody

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/containers/{id}`

Delete a container (its chat log stays)

Path parameters

Name	Type	Description
`id`	`string`

Query parameters

Name	Type	Description
`force`optional	`"true" \| "false"`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/close`

Close a container: it is archived and can be reopened

Path parameters

Name	Type	Description
`id`	`string`

Query parameters

Name	Type	Description
`force`optional	`"true" \| "false"`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/reopen`

Reopen a closed container

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/chat-log-block`

Put the conversation on the workspace canvas as a chat-log block

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/retry`

Retry a container whose creation failed

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/repos`

Check repositories out in the container (new worktrees, read-only checkouts, or read-only ones made writable)

Path parameters

Name	Type	Description
`id`	`string`

Request body: AttachContainerReposBody

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/start`

Work: the agent implements the spec

Path parameters

Name	Type	Description
`id`	`string`

Request body: StartContainerBody

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/stop`

Stop the agent (a container being worked on returns to draft)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/done`

Mark the work as done

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/push`

Push every worktree branch with the caller's GitHub token

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/prs`

Open pull requests as the caller

Path parameters

Name	Type	Description
`id`	`string`

Request body: ContainerPrsBody

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/merge`

Merge the open pull requests as the caller

Path parameters

Name	Type	Description
`id`	`string`

Request body: ContainerMergeBody

200 OK: Container

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/links`

Link workspace blocks into the container

Path parameters

Name	Type	Description
`id`	`string`

Request body: ContainerBlocksBody

200 OK

Name	Type	Description
`copied`	`integer`

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/containers/{id}/links/{block}`

Unlink a block from the container

Path parameters

Name	Type	Description
`id`	`string`
`block`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/sync-back`

Bring container-canvas edits to the workspace originals, merged with the workspace's own changes; what cannot be merged is a conflict

Path parameters

Name	Type	Description
`id`	`string`

Request body: ContainerBlocksBody

200 OK: SyncBackResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/discard-edits`

Throw away container-canvas edits

Path parameters

Name	Type	Description
`id`	`string`

Request body: ContainerBlocksBody

200 OK

Name	Type	Description
`copied`	`integer`

Errors: 400, 401, 403, 404, 409, 429 with an error body

Apps

GET `/v1/workspaces/{ws}/apps/env`

The workspace's env values for apps (secret values are never returned)

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: AppEnvList

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/workspaces/{ws}/apps/env`

Replace the workspace's env values for apps; a secret sent without a value keeps the stored one

Path parameters

Name	Type	Description
`ws`	`string`

Request body: PutAppEnvBody

200 OK: AppEnvList

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/containers/{id}/apps/env`

The project's env values for apps (secret values are never returned)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: AppEnvList

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/containers/{id}/apps/env`

Replace the project's env values for apps; they win over the workspace's

Path parameters

Name	Type	Description
`id`	`string`

Request body: PutAppEnvBody

200 OK: AppEnvList

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/apps`

The workspace's app configs (its own layer)

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: AppConfigList

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/apps/{repo}/{name}`

One app config of the workspace layer

Path parameters

Name	Type	Description
`ws`	`string`
`repo`	`string`
`name`	`string`

200 OK: AppConfig

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/workspaces/{ws}/apps/{repo}/{name}`

Create or replace an app in the workspace layer (every project of the workspace sees it); disabled hides an org default

Path parameters

Name	Type	Description
`ws`	`string`
`repo`	`string`
`name`	`string`

Request body: PutAppConfigBody

200 OK: AppConfig

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/workspaces/{ws}/apps/{repo}/{name}`

Remove an app from the workspace layer

Path parameters

Name	Type	Description
`ws`	`string`
`repo`	`string`
`name`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/apps/{repo}/save-as-default`

Make the workspace's apps of a repository the org default for it (org admins)

Path parameters

Name	Type	Description
`ws`	`string`
`repo`	`string`

200 OK: AppConfigList

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/apps/settings`

Which hoster the workspace's apps run on

Path parameters

Name	Type	Description
`ws`	`string`

200 OK: WorkspaceAppsSettings

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/workspaces/{ws}/apps/settings`

Choose the hoster the workspace's apps run on (null: the org's, else an official one)

Path parameters

Name	Type	Description
`ws`	`string`

Request body: PutWorkspaceAppsSettingsBody

200 OK: WorkspaceAppsSettings

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/containers/{id}/apps/config/{repo}/{name}`

A project-layer app config

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

200 OK: AppConfig

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/containers/{id}/apps/config/{repo}/{name}`

Create or replace an app in the project layer (only this project sees it); disabled hides an inherited app here

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

Request body: PutAppConfigBody

200 OK: AppConfig

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/containers/{id}/apps/config/{repo}/{name}`

Remove an app from the project layer

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/config/{repo}/{name}/promote`

Move a project-layer app to the workspace layer, so every project sees it

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

200 OK: AppConfig

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/orgs/{org}/repos/{repo}/apps`

The org default apps of a repository

Path parameters

Name	Type	Description
`org`	`string`
`repo`	`string`

200 OK: AppConfigList

Errors: 400, 401, 403, 404, 409, 429 with an error body

PUT `/v1/orgs/{org}/repos/{repo}/apps/{name}`

Create or replace an org default app (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`repo`	`string`
`name`	`string`

Request body: PutAppConfigBody

200 OK: AppConfig

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/orgs/{org}/repos/{repo}/apps/{name}`

Remove an org default app (org admins)

Path parameters

Name	Type	Description
`org`	`string`
`repo`	`string`
`name`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/containers/{id}/apps`

A project's apps: their config after the layers are merged, and their instances on the hoster

Path parameters

Name	Type	Description
`id`	`string`

200 OK: ProjectApps

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/{repo}/{name}/start`

Start an app (and what it depends on)

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

Request body: AppActionBody

200 OK: ProjectApps

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/{repo}/{name}/stop`

Stop an app; its data stays

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

Request body: AppActionBody

200 OK: ProjectApps

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/{repo}/{name}/restart`

Restart an app; it is rebuilt only when the source changed

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

Request body: AppActionBody

200 OK: ProjectApps

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/{repo}/{name}/reset`

Remove an app's container, image and logs, and its data unless keepData

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

Request body: AppActionBody

200 OK: ProjectApps

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/start`

Start every app of the project, in dependency order

Path parameters

Name	Type	Description
`id`	`string`

Request body: AppActionBody

200 OK: ProjectApps

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/stop`

Stop every app of the project

Path parameters

Name	Type	Description
`id`	`string`

Request body: AppActionBody

200 OK: ProjectApps

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/reset`

Reset every app of the project

Path parameters

Name	Type	Description
`id`	`string`

Request body: AppActionBody

200 OK: ProjectApps

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/containers/{id}/apps/{repo}/{name}/logs`

The backlog of an app's build and run log (live lines follow as app.log events)

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

Query parameters

Name	Type	Description
`since`optional	`integer \| null`
`tail`optional	`integer`

200 OK: AppLogs

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/containers/{id}/apps/{repo}/{name}/db/tables`

Tables of a database app

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

200 OK

Name	Type	Description
`tables`	`DbTable[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/containers/{id}/apps/{repo}/{name}/db/rows`

A page of rows of one table of a database app

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

Query parameters

Name	Type	Description
`table`	`string`
`offset`optional	`integer \| null`
`limit`optional	`integer`

200 OK: DbRows

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/containers/{id}/apps/{repo}/{name}/db/query`

A read-only query on a database app (writes are refused)

Path parameters

Name	Type	Description
`id`	`string`
`repo`	`string`
`name`	`string`

Request body: DbQueryBody

200 OK: DbRows

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/hosted/auth/ticket`

A short-lived ticket that opens one team app's host for the caller, if they can see its project

Request body: HostedTicketBody

200 OK: HostedTicket

Errors: 400, 401, 403, 404, 409, 429 with an error body

Conflicts

GET `/v1/workspaces/{ws}/conflicts`

Files two writers changed in ways that could not be merged (open ones by default)

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`status`optional	`"open" \| "resolved" \| "all"`

200 OK: ConflictList

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/workspaces/{ws}/conflicts/{id}`

One conflict, with its versions when they are text

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

200 OK: FileConflictDetail

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/conflicts/{id}/resolve`

Settle a conflict: keep one version, keep both, or write the merged text. Recorded in the history.

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

Request body: ResolveConflictBody

200 OK: ResolveConflictResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/conflicts/{id}/ask-agent`

Ask your agent, in your workspace chat, to propose a merged version for you to review

Path parameters

Name	Type	Description
`ws`	`string`
`id`	`string`

200 OK: AskConflictAgentResult

Errors: 400, 401, 403, 404, 409, 429 with an error body

Comments

GET `/v1/workspaces/{ws}/comments`

Comment threads on the workspace canvas, or on a project's canvas and spec

Path parameters

Name	Type	Description
`ws`	`string`

Query parameters

Name	Type	Description
`container`optional	`string`

200 OK

Name	Type	Description
`threads`	`CommentThread[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/workspaces/{ws}/comments`

Start a comment thread on a block or a passage

Path parameters

Name	Type	Description
`ws`	`string`

Request body: StartThreadBody

200 OK: CommentThread

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/comment-threads/{id}/comments`

Answer in a comment thread

Path parameters

Name	Type	Description
`id`	`string`

Request body: ReplyBody

200 OK: CommentThread

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/comment-threads/{id}/resolve`

Mark a thread resolved

Path parameters

Name	Type	Description
`id`	`string`

200 OK: CommentThread

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/comment-threads/{id}/reopen`

Open a resolved thread again

Path parameters

Name	Type	Description
`id`	`string`

200 OK: CommentThread

Errors: 400, 401, 403, 404, 409, 429 with an error body

PATCH `/v1/comments/{id}`

Change your own comment

Path parameters

Name	Type	Description
`id`	`string`

Request body: EditCommentBody

200 OK: CommentThread

Errors: 400, 401, 403, 404, 409, 429 with an error body

DELETE `/v1/comments/{id}`

Delete your comment (workspace owners: any comment)

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

Notifications

GET `/v1/notifications`

The caller's recent notifications

200 OK

Name	Type	Description
`notifications`	`Notification[]`
`unread`	`integer`

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/notifications/read-all`

Mark every notification as read

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/notifications/clear`

Remove every notification of the caller

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

POST `/v1/notifications/{id}/read`

Mark a notification as read

Path parameters

Name	Type	Description
`id`	`string`

200 OK: Ok

Errors: 400, 401, 403, 404, 409, 429 with an error body

Feedback

POST `/v1/feedback`

Send a request or a problem to the people who build Yard

Request body: FeedbackBody

200 OK

Name	Type	Description
`id`	`string`

Errors: 400, 401, 403, 404, 409, 429 with an error body

GET `/v1/admin/feedback`

Everything people sent, the inbox or the archived (instance admins)

Query parameters

Name	Type	Description
`archived`optional	`"true" \| "false"`

200 OK

Name	Type	Description
`feedback`	`Feedback[]`

Errors: 400, 401, 403, 404, 409, 429 with an error body

Screenshots

POST `/v1/workspaces/{ws}/screenshots`

Screenshot a URL or the virtual display from inside a box

Path parameters

Name	Type	Description
`ws`	`string`

Request body: ScreenshotBody

200 OK: Screenshot

Errors: 400, 401, 403, 404, 409, 429 with an error body

Direct runner domains

POST `/v1/workspaces/{ws}/direct`

A one-minute ticket to open a terminal or read files straight from the workspace's runner, when it has its own address

Path parameters

Name	Type	Description
`ws`	`string`

Request body: DirectTicketBody

200 OK: DirectTicket

Errors: 400, 401, 403, 404, 409, 429 with an error body

Errors

Every error answers with the same body:

ErrorBody

Name	Type	Description
`error`	`string`
`code`	`string`

Schemas

AcceptedInvite

Fields

Name	Type	Description
`org`	`object`
`workspaceId`	`string \| null`

AdminClaimState

Fields

Name	Type	Description
`open`	`boolean`
`method`	`"code" \| "button"`
`isAdmin`	`boolean`
`isOwner`	`boolean`

AdminOverview

Fields

Name	Type	Description
`users`	`integer`
`orgs`	`integer`
`workspaces`	`integer`
`runners`	`object`
`turnsLastDay`	`integer`
`openFeedback`	`integer`
`failedEmailsLastDay`	`integer`

AdminSystem

Fields

Name	Type	Description
`version`	`string`
`migrations`	`integer`
`email`	`object`
`storage`	`object`
`githubApp`	`boolean`
`masterKey`	`"env" \| "file"`
`directTickets`	`boolean`

AdminUser

Fields

Name	Type	Description
`id`	`string`
`name`	`string`
`email`	`string`
`isAdmin`	`boolean`
`isOwner`	`boolean`
`disabled`	`boolean`
`sessions`	`integer`
`orgs`	`integer`
`createdAt`	`string`

AgentAccount

Fields

Name	Type	Description
`id`	`string`
`provider`	`"claude" \| "codex" \| "cursor" \| "fake"`
`label`	`string`
`status`	`"pending" \| "active" \| "expired"`
`auth`	`"login" \| "api_key"`
`isActive`	`boolean`
`workspaces`	`object[]`
`lastUsedAt`	`string \| null`
`createdAt`	`string`

AgentLoginCodeBody

Fields

Name	Type	Description
`code`	`string`

AgentLoginState

Fields

Name	Type	Description
`accountId`	`string`
`phase`	`"none" \| "starting" \| "awaiting_code" \| "awaiting_device" \| "verifying" \| "authorized" \| "error" \| "expired"`
`url`	`string \| null`
`userCode`	`string \| null`
`error`	`string \| null`

ApiKey

Fields

Name	Type	Description
`id`	`string`
`kind`	`"user" \| "org"`
`name`	`string`
`prefix`	`string`
`scopes`	`("read" \| "write" \| "runners" \| "admin")[]`
`role`	`"admin" \| "member" \| null`
`createdBy`	`object \| null`
`createdAt`	`string`
`expiresAt`	`string \| null`
`lastUsedAt`	`string \| null`
`lastUsedIp`	`string \| null`
`previousExpiresAt`	`string \| null`

AppActionBody

Fields

Name	Type	Description
`keepData`optional	`boolean`

AppConfig

Fields

Name	Type	Description
`id`	`string`
`layer`	`AppConfigLayer`
`repo`	`string`
`repoId`	`string`
`name`	`string`
`spec`	`object`
`disabled`	`boolean`
`updatedBy`	`string \| null`
`updatedAt`	`string`

AppConfigLayer

"org" | "workspace" | "project"

AppConfigList

Fields

Name	Type	Description
`configs`	`AppConfig[]`

AppEnvEntry

Fields

Name	Type	Description
`repo`	`string \| null`
`app`	`string \| null`
`name`	`string`
`value`	`string \| null`
`secret`	`boolean`
`set`	`boolean`

AppEnvList

Fields

Name	Type	Description
`entries`	`AppEnvEntry[]`

AppInstance

Fields

Name	Type	Description
`id`	`string`
`state`	`"pending" \| "fetching" \| "building" \| "starting" \| "running" \| "sleeping" \| "stopped" \| "error"`
`urls`	`AppUrl[]`
`sourceSha`	`string \| null`
`hosterId`	`string`
`startedBy`	`string \| null`
`error`	`string \| null`
`updatedAt`	`string`

AppLogs

Fields

Name	Type	Description
`lines`	`object[]`

AppUrl

Fields

Name	Type	Description
`port`	`string`
`url`	`string`
`visibility`	`"team" \| "public"`

AskConflictAgentResult

Fields

Name	Type	Description
`chatId`	`string`

AttachContainerReposBody

Fields

Name	Type	Description
`repos`	`object[]`

AuthProviders

Fields

Name	Type	Description
`github`	`boolean`

ChangePasswordBody

Fields

Name	Type	Description
`current`	`string`
`next`	`string`

Chat

Fields

Name	Type	Description
`id`	`string`
`workspaceId`	`string`
`containerId`	`string \| null`
`owner`	`object \| null`
`forkedFrom`	`ChatFork`
`status`	`"idle" \| "running" \| "awaiting_input" \| "error"`
`messages`	`ChatMessage[]`
`hasMore`	`boolean`
`queue`	`ChatQueueItem[]`
`live`	`ChatLive`

ChatActivity

Fields

Name	Type	Description
`id`	`string`
`kind`	`"read" \| "edit" \| "run" \| "search" \| "other"`
`label`	`string`
`detail`optional	`string`
`ok`optional	`boolean`
`done`	`boolean`
`input`optional	`string`
`output`optional	`string`

ChatFork

Fields

Name	Type	Description
`chatId`	`string`
`owner`	`object \| null`
`seq`	`integer`

ChatGitEvent

Fields

Name	Type	Description
`kind`	`"pushed" \| "pr_opened" \| "pr_merged" \| "pr_closed" \| "pr_reopened" \| "pr_conflicting"`
`repo`	`string`
`branch`	`string`
`base`optional	`string`
`commits`optional	`integer`
`number`optional	`integer`
`url`optional	`string`
`by`	`string \| null`
`onGitHub`	`boolean`

ChatLive

Fields

Name	Type	Description
`turnId`	`string`
`text`	`string`
`activity`	`ChatActivity[]`
`todos`	`object[]`
`queuedPosition`	`integer \| null`
`queuedReason`	`"concurrency" \| "load" \| null`
`load`	`object \| null`
`startedBy`	`string`

ChatLoadNotice

Fields

Name	Type	Description
`state`	`"queued" \| "started" \| "paused" \| "restarted" \| "expired"`
`position`optional	`integer`
`cpuPercent`optional	`number \| null`
`memPercent`optional	`number \| null`

ChatMessage

Fields

Name	Type	Description
`id`	`string`
`chatId`	`string`
`seq`	`integer`
`role`	`"user" \| "agent" \| "system"`
`author`	`object \| null`
`text`	`string`
`context`	`object[]`
`attachments`	`string[]`
`activity`	`ChatActivity[]`
`questions`	`object[]`
`actions`	`(object \| object \| object)[]`
`feedbackSent`	`string[]`
`error`	`object \| null`
`cancelled`	`boolean`
`agent`	`object \| null`
`git`	`ChatGitEvent`
`load`	`ChatLoadNotice`
`usage`	`ChatUsageNotice`
`createdAt`	`string`

ChatQueueItem

Fields

Name	Type	Description
`id`	`string`
`chatId`	`string`
`author`	`object`
`text`	`string`
`held`	`boolean`
`createdAt`	`string`

ChatUsageNotice

Fields

Name	Type	Description
`resetsAt`	`string \| null`
`held`	`boolean`

CliLoginPoll

Fields

Name	Type	Description
`status`	`"pending" \| "approved" \| "denied" \| "expired"`
`key`optional	`string`
`keyId`optional	`string`

CliLoginRequest

Fields

Name	Type	Description
`code`	`string`
`hostname`	`string`
`scopes`	`("read" \| "write" \| "runners" \| "admin")[]`
`status`	`"pending" \| "approved" \| "denied" \| "expired"`
`expiresAt`	`string`

CliLoginStart

Fields

Name	Type	Description
`code`	`string`
`deviceToken`	`string`
`verifyUrl`	`string`
`interval`	`integer`
`expiresAt`	`string`

CliLoginStartBody

Fields

Name	Type	Description
`hostname`	`string`
`scopes`optional	`("read" \| "write" \| "runners" \| "admin")[]`

Comment

Fields

Name	Type	Description
`id`	`string`
`author`	`object \| null`
`body`	`string`
`createdAt`	`string`
`editedAt`	`string \| null`
`deleted`	`boolean`

CommentThread

Fields

Name	Type	Description
`id`	`string`
`workspaceId`	`string`
`containerId`	`string \| null`
`anchor`	`object \| object`
`resolved`	`boolean`
`resolvedBy`	`object \| null`
`createdAt`	`string`
`comments`	`Comment[]`

CommitBody

Fields

Name	Type	Description
`message`	`string`

ConflictList

Fields

Name	Type	Description
`conflicts`	`FileConflict[]`

ConflictSide

Fields

Name	Type	Description
`kind`	`"person" \| "agent" \| "project" \| "disk"`
`name`	`string`
`userId`optional	`string`
`container`optional	`string`
`containerId`optional	`string`

ConnectIntegrationBody

Fields

Name	Type	Description
`apiKey`	`string`

ConnectRepoBody

Fields

Name	Type	Description
`fullName`	`string`

Container

Fields

Name	Type	Description
`id`	`string`
`workspaceId`	`string`
`slug`	`string`
`title`	`string`
`instructions`	`string`
`flow`	`"spec" \| "direct"`
`status`	`"creating" \| "draft" \| "ready" \| "done"`
`agentState`	`"idle" \| "running" \| "awaiting_input" \| "error"`
`error`	`string \| null`
`activity`	`ContainerActivity`
`plan`	`object[]`
`criteria`	`object`
`chatId`	`string`
`blockId`	`string \| null`
`links`	`string[]`
`chatLogBlockId`	`string \| null`
`closedAt`	`string \| null`
`agent`	`object`
`repos`	`ContainerRepo[]`
`additions`	`integer`
`deletions`	`integer`
`createdBy`	`object \| null`
`createdAt`	`string`
`updatedAt`	`string`

ContainerActivity

Fields

Name	Type	Description
`text`	`string`
`steps`	`string[]`
`writingSpec`	`boolean`

ContainerBlocksBody

Fields

Name	Type	Description
`blockIds`	`string[]`
`sheetId`optional	`string \| null`

ContainerMergeBody

Fields

Name	Type	Description
`method`optional	`"merge" \| "squash" \| "rebase"`

ContainerPrsBody

Fields

Name	Type	Description
`title`optional	`string`
`body`optional	`string`

ContainerRepo

Fields

Name	Type	Description
`repoId`	`string`
`slug`	`string`
`fullName`	`string`
`mode`	`"worktree" \| "readonly"`
`branch`	`string`
`base`	`string`
`additions`	`integer`
`deletions`	`integer`
`commits`	`integer`
`dirty`	`integer`
`pushed`	`boolean`
`unpushed`	`integer`
`aheadBase`	`integer`
`behindBase`	`integer`
`upstreamBehind`	`integer`
`operation`	`"merge" \| "rebase" \| "cherry_pick" \| "revert" \| null`
`conflicted`	`string[]`
`worktreeRemoved`	`boolean`
`pr`	`object \| null`

CreateAgentAccountBody

Fields

Name	Type	Description
`provider`	`"claude" \| "codex" \| "cursor" \| "fake"`
`label`optional	`string`
`apiKey`optional	`string`

CreateApiKeyBody

Fields

Name	Type	Description
`name`	`string`
`scopes`	`("read" \| "write" \| "runners" \| "admin")[]`
`expiresInDays`optional	`integer`
`role`optional	`"admin" \| "member"`

CreateContainerBody

Fields

Name	Type	Description
`instructions`	`string`
`flow`optional	`"spec" \| "direct"`
`title`optional	`string`
`blockIds`optional	`string[]`
`sheetId`optional	`string \| null`
`repos`optional	`object[]`
`attachments`optional	`string[]`
`x`optional	`number`
`y`optional	`number`
`provider`optional	`"claude" \| "codex" \| "cursor" \| "fake"`
`model`optional	`string`
`effort`optional	`string`

CreatedApiKey

Fields

Name	Type	Description
`key`	`ApiKey`
`secret`	`string`

CreatedHoster

Fields

Name	Type	Description
`hoster`	`Hoster`
`token`	`string`
`command`	`string`

CreatedInvite

Fields

Name	Type	Description
`invite`	`Invite`
`url`	`string`

CreatedRunner

Fields

Name	Type	Description
`runner`	`Runner`
`token`	`string`
`command`	`string`
`installCommand`	`string`
`installCommandWindows`	`string`
`compose`	`object`

CreateInviteBody

Fields

Name	Type	Description
`email`optional	`string`
`role`optional	`"admin" \| "member"`
`maxUses`optional	`integer`

CreateOfficialHosterBody

Fields

Name	Type	Description
`name`	`string`
`domain`	`string`

CreateOrgBody

Fields

Name	Type	Description
`name`	`string`
`slug`optional	`string`

CreateRepoBody

Fields

Name	Type	Description
`name`	`string`
`private`optional	`boolean`
`owner`optional	`string`

CreateRunnerBody

Fields

Name	Type	Description
`name`	`string`

CreateSheetBody

Fields

Name	Type	Description
`name`	`string`

CreateStorageBucketBody

Fields

Name	Type	Description
`name`	`string`
`provider`	`"r2" \| "s3" \| "gcs" \| "s3c"`
`endpoint`optional	`string`
`region`optional	`string`
`bucket`	`string`
`accessKeyId`	`string`
`secretAccessKey`	`string`
`isDefault`optional	`boolean`
`acceptsNew`optional	`boolean`

CreateTerminalBody

Fields

Name	Type	Description
`container`optional	`string`
`new`optional	`boolean`

CreateUploadBody

Fields

Name	Type	Description
`name`	`string`
`size`	`integer`
`contentType`optional	`string`
`container`optional	`string`
`purpose`optional	`"uploads" \| "attachments"`

CreateWorkspaceBody

Fields

Name	Type	Description
`name`	`string`
`runnerId`	`string`
`useGpu`optional	`boolean`
`storageBucketId`optional	`string`

DbQueryBody

Fields

Name	Type	Description
`sql`	`string`

DbRows

Fields

Name	Type	Description
`columns`	`string[]`
`rows`	`((string \| null)[])[]`
`truncated`	`boolean`

DirectTicket

Fields

Name	Type	Description
`url`	`string`
`ticket`	`string`
`expiresAt`	`string`

DirectTicketBody

Fields

Name	Type	Description
`purpose`	`"terminal" \| "file"`
`terminalId`optional	`string`
`container`optional	`string`

DiscardBody

Fields

Name	Type	Description
`paths`	`string[]`

EditCommentBody

Fields

Name	Type	Description
`body`	`string`

EmailEvent

Fields

Name	Type	Description
`id`	`string`
`to`	`string`
`kind`	`string`
`subject`	`string`
`transport`	`string`
`status`	`"sent" \| "failed" \| "logged"`
`error`	`string \| null`
`at`	`string`

EmailFactorDisableBody

Fields

Name	Type	Description
`password`	`string`

FeedbackBody

Fields

Name	Type	Description
`kind`	`"feature" \| "bug" \| "other"`
`title`	`string`
`body`optional	`string`
`workspaceId`optional	`string`
`chatId`optional	`string`
`messageId`optional	`string`
`context`optional	`FeedbackContext`

FeedbackContext

Fields

Name	Type	Description
`path`optional	`string`
`orgId`optional	`string`
`workspaceId`optional	`string`
`containerId`optional	`string`
`appVersion`optional	`string`
`viewport`optional	`object`

FileConflict

Fields

Name	Type	Description
`id`	`string`
`workspaceId`	`string`
`container`	`string \| null`
`path`	`string`
`title`	`string \| null`
`kind`	`"text" \| "image" \| "binary"`
`source`	`"save" \| "sync-back" \| "transfer" \| "canvas"`
`blockId`	`string \| null`
`ours`	`ConflictSide`
`theirs`	`ConflictSide`
`hasBase`	`boolean`
`status`	`"open" \| "resolved"`
`resolution`	`"ours" \| "theirs" \| "both" \| "merged" \| "superseded" \| null`
`resolvedBy`	`string \| null`
`resolvedAt`	`string \| null`
`createdAt`	`string`

FileConflictDetail

Fields

Name	Type	Description
`id`	`string`
`workspaceId`	`string`
`container`	`string \| null`
`path`	`string`
`title`	`string \| null`
`kind`	`"text" \| "image" \| "binary"`
`source`	`"save" \| "sync-back" \| "transfer" \| "canvas"`
`blockId`	`string \| null`
`ours`	`ConflictSide`
`theirs`	`ConflictSide`
`hasBase`	`boolean`
`status`	`"open" \| "resolved"`
`resolution`	`"ours" \| "theirs" \| "both" \| "merged" \| "superseded" \| null`
`resolvedBy`	`string \| null`
`resolvedAt`	`string \| null`
`createdAt`	`string`
`text`	`object \| null`
`proposal`	`string \| null`

FileContent

Fields

Name	Type	Description
`path`	`string`
`content`	`string`
`binary`	`boolean`
`size`	`number`
`truncated`	`boolean`

FileList

Fields

Name	Type	Description
`files`	`string[]`
`truncated`	`boolean`

GitAbortResult

Fields

Name	Type	Description
`aborted`	`"merge" \| "rebase" \| "cherry_pick" \| "revert"`

GitConflicts

Fields

Name	Type	Description
`conflicts`	`boolean`
`files`	`string[]`
`base`	`string`

GitDiff

Fields

Name	Type	Description
`diff`	`string`
`truncated`	`boolean`

GithubDisconnectPreview

Fields

Name	Type	Description
`repos`	`GithubDisconnectRepo[]`

GithubDisconnectRepo

Fields

Name	Type	Description
`id`	`string`
`fullName`	`string`
`orgSlug`	`string`
`orgName`	`string`
`workspaces`	`object[]`
`blockedBy`	`string \| null`

GithubDisconnectResult

Fields

Name	Type	Description
`ok`	`true`
`removed`	`integer`
`kept`	`string[]`

GithubIdentity

Fields

Name	Type	Description
`connected`	`boolean`
`login`	`string \| null`
`name`	`string \| null`
`email`	`string \| null`
`kind`	`"app" \| "pat" \| null`
`usable`	`boolean`

GithubInstallation

Fields

Name	Type	Description
`id`	`string`
`installationId`	`integer`
`accountLogin`	`string`
`accountType`	`string`
`suspended`	`boolean`

GithubPeek

object | object | object | object | object

GithubSigninBody

Fields

Name	Type	Description
`next`optional	`string`

GithubSignupBody

Fields

Name	Type	Description
`ticket`	`string`
`email`	`string`
`password`	`string`
`name`	`string`

GithubSignupPending

Fields

Name	Type	Description
`login`	`string`
`name`	`string \| null`
`email`	`string \| null`

GitPullResult

Fields

Name	Type	Description
`updated`	`boolean`
`head`	`string \| null`

GitStatus

Fields

Name	Type	Description
`branch`	`string \| null`
`head`	`string \| null`
`dirty`	`integer`
`ahead`	`integer`
`behind`	`integer`
`upstream`	`string \| null`
`additions`	`integer`
`deletions`	`integer`
`aheadBase`	`integer`
`behindBase`	`integer`
`operation`	`"merge" \| "rebase" \| "cherry_pick" \| "revert" \| null`
`conflicted`	`string[]`
`base`	`string \| null`

GitUpdateResult

Fields

Name	Type	Description
`result`	`"merged" \| "up_to_date" \| "conflict"`
`head`	`string \| null`
`files`	`string[]`
`base`	`string`

GrepResult

Fields

Name	Type	Description
`matches`	`object[]`
`truncated`	`boolean`

Health

Fields

Name	Type	Description
`ok`	`boolean`
`version`	`string`
`time`	`string`

History

Fields

Name	Type	Description
`head`	`string \| null`
`dirty`	`string[]`
`commits`	`HistoryCommit[]`

HistoryCommit

Fields

Name	Type	Description
`sha`	`string`
`short`	`string`
`message`	`string`
`author`	`string`
`date`	`string`
`isHead`	`boolean`

HistoryResult

Fields

Name	Type	Description
`sha`	`string \| null`

HostedTicket

Fields

Name	Type	Description
`redirect`	`string`
`ticket`	`string`
`expiresAt`	`string`

HostedTicketBody

Fields

Name	Type	Description
`url`	`string`

Hoster

Fields

Name	Type	Description
`id`	`string`
`name`	`string`
`kind`	`"official" \| "org"`
`online`	`boolean`
`domain`	`string \| null`
`tls`	`string \| null`
`version`	`string \| null`
`hostname`	`string \| null`
`lastSeenAt`	`string \| null`
`device`	`"pinned" \| "unpinned"`
`createdAt`	`string`

InstallUrl

Fields

Name	Type	Description
`url`	`string`

Integration

Fields

Name	Type	Description
`provider`	`IntegrationProvider`
`connected`	`boolean`
`hint`	`string \| null`
`connectedAt`	`string \| null`
`unreadable`	`boolean`

IntegrationList

Fields

Name	Type	Description
`integrations`	`Integration[]`

IntegrationProvider

"mistral"

Invite

Fields

Name	Type	Description
`id`	`string`
`email`	`string \| null`
`role`	`"owner" \| "admin" \| "member"`
`workspaceId`	`string \| null`
`workspaceRole`	`"owner" \| "editor" \| "viewer" \| null`
`maxUses`	`integer \| null`
`uses`	`integer`
`expiresAt`	`string`
`createdAt`	`string`
`invitedBy`	`string`

InvitePreview

Fields

Name	Type	Description
`orgName`	`string`
`orgSlug`	`string`
`role`	`"owner" \| "admin" \| "member"`
`email`	`string \| null`
`invitedBy`	`string`
`workspaceName`	`string \| null`

KillProcessBody

Fields

Name	Type	Description
`container`optional	`string`
`pid`	`integer`

LinkPreview

Fields

Name	Type	Description
`url`	`string`
`title`	`string \| null`
`description`	`string \| null`
`image`	`string \| null`
`site`	`string \| null`
`frameable`optional	`boolean`

LinkPreviewBody

Fields

Name	Type	Description
`url`	`string`

Me

Fields

Name	Type	Description
`user`	`User`
`orgs`	`OrgSummary[]`

Member

Fields

Name	Type	Description
`userId`	`string`
`name`	`string`
`email`	`string`
`role`	`"owner" \| "admin" \| "member"`
`joinedAt`	`string`

MergePrBody

Fields

Name	Type	Description
`method`optional	`"merge" \| "squash" \| "rebase"`

MountRepoBody

Fields

Name	Type	Description
`repoId`	`string`

Ok

Fields

Name	Type	Description
`ok`	`true`

OpenPrBody

Fields

Name	Type	Description
`title`	`string`
`body`optional	`string`

Org

Fields

Name	Type	Description
`id`	`string`
`slug`	`string`
`name`	`string`
`plan`	`string`
`retentionDays`	`integer`
`defaultAgent`	`string \| null`
`defaultModel`	`string \| null`
`defaultEffort`	`string \| null`
`allowedEmailDomains`	`string[]`
`role`	`"owner" \| "admin" \| "member"`
`memberCount`	`integer`
`createdAt`	`string`

OrgGithub

Fields

Name	Type	Description
`configured`	`boolean`
`appSlug`	`string \| null`
`installations`	`GithubInstallation[]`
`me`	`GithubIdentity`

OrgStorage

Fields

Name	Type	Description
`kind`	`"managed" \| "r2" \| "s3" \| "gcs"`
`endpoint`	`string \| null`
`region`	`string \| null`
`bucket`	`string \| null`
`accessKeyId`	`string \| null`
`hasSecret`	`boolean`
`usable`	`boolean`

OrgSummary

Fields

Name	Type	Description
`id`	`string`
`slug`	`string`
`name`	`string`
`role`	`"owner" \| "admin" \| "member"`

OrgUsage

Fields

Name	Type	Description
`measuredAt`	`string`
`totals`	`object`
`workspaces`	`object[]`

Passkey

Fields

Name	Type	Description
`id`	`string`
`name`	`string`
`createdAt`	`string`
`lastUsedAt`	`string \| null`

PasskeyLoginBody

Fields

Name	Type	Description
`ticket`	`string`
`challengeId`optional	`string`
`response`	`object`

PasskeyLoginOptionsBody

Fields

Name	Type	Description
`challengeId`optional	`string`

PasskeyRegisterBody

Fields

Name	Type	Description
`name`	`string`
`response`	`object`

ProcessList

Fields

Name	Type	Description
`supported`	`boolean`
`processes`	`object[]`

ProjectApps

Fields

Name	Type	Description
`apps`	`ResolvedApp[]`
`hidden`	`object[]`
`hoster`	`object \| null`
`blocked`	`string \| null`

PullRequest

Fields

Name	Type	Description
`number`	`integer`
`url`	`string`
`title`	`string`
`state`	`"open" \| "closed" \| "merged"`
`draft`	`boolean`

PullRequestState

Fields

Name	Type	Description
`pr`	`PullRequest`
`pushed`	`boolean`
`mergeable`	`"mergeable" \| "conflicting" \| "unknown" \| null`

PutAppConfigBody

Fields

Name	Type	Description
`spec`	`object`

PutAppEnvBody

Fields

Name	Type	Description
`entries`	`object[]`

PutWorkspaceAppsSettingsBody

Fields

Name	Type	Description
`hosterId`	`string \| null`

RecoveryCodes

Fields

Name	Type	Description
`recoveryCodes`	`string[]`

RemovePathsBody

Fields

Name	Type	Description
`paths`	`string[]`

ReplyBody

Fields

Name	Type	Description
`body`	`string`

Repo

Fields

Name	Type	Description
`id`	`string`
`slug`	`string`
`fullName`	`string`
`description`	`string \| null`
`private`	`boolean`
`defaultBranch`	`string`
`createdAt`	`string`

RepoBranches

Fields

Name	Type	Description
`branches`	`string[]`
`current`	`string`

ResolveConflictBody

object | object

ResolveConflictResult

Fields

Name	Type	Description
`conflict`	`FileConflict`
`keptAs`	`string \| null`
`sha`	`string \| null`

ResolvedApp

Fields

Name	Type	Description
`repo`	`string`
`repoId`	`string`
`name`	`string`
`source`	`AppConfigLayer`
`spec`	`object`
`overrides`	`AppConfigLayer & string \| null`
`missing`	`string[]`
`noWorktree`	`boolean`
`instance`	`AppInstance`

RetryFailedBody

Fields

Name	Type	Description
`workspaceId`optional	`string`

RetryFailedResult

Fields

Name	Type	Description
`chats`	`integer`
`projects`	`integer`

RotateApiKeyBody

Fields

Name	Type	Description
`graceHours`optional	`integer`

RotatedRunnerToken

Fields

Name	Type	Description
`runner`	`Runner`
`token`	`string`
`command`	`string`
`installCommand`	`string`
`installCommandWindows`	`string`
`compose`	`object`
`delivered`	`boolean`
`fromEnv`	`boolean`

Runner

Fields

Name	Type	Description
`id`	`string`
`name`	`string`
`kind`	`"official" \| "official-pro" \| "org" \| "personal"`
`online`	`boolean`
`capabilities`	`object \| null`
`version`	`string \| null`
`lastSeenAt`	`string \| null`
`workspaceCount`	`integer`
`createdAt`	`string`
`device`	`RunnerDevice`
`direct`	`RunnerDirect`
`owner`	`object \| null`
`mine`	`boolean`
`othersCanEdit`	`boolean`
`agentConcurrency`	`integer \| null`
`load`	`RunnerLoadSettings`

RunnerDevice

Fields

Name	Type	Description
`state`	`"pinned" \| "unpinned" \| "pending"`
`hostname`	`string \| null`
`os`	`string \| null`
`pinnedAt`	`string \| null`
`change`	`RunnerDeviceChange`

RunnerDeviceChange

Fields

Name	Type	Description
`id`	`string`
`hostname`	`string`
`os`	`string`
`arch`	`string`
`ip`	`string \| null`
`firstSeenAt`	`string`
`lastSeenAt`	`string`
`waiting`	`boolean`

RunnerDirect

Fields

Name	Type	Description
`url`	`string`
`status`	`"unverified" \| "ok" \| "unreachable"`
`checkedAt`	`string \| null`
`error`	`string \| null`

RunnerLoadPatch

Fields

Name	Type	Description
`cpuThreshold`optional	`integer`
`memoryThreshold`optional	`integer`
`hysteresis`optional	`integer`
`maxQueueWaitMinutes`optional	`integer \| null`
`autoPauseIdleBoxes`optional	`boolean`
`busyIdleMinutes`optional	`integer`

RunnerLoadSettings

Fields

Name	Type	Description
`cpuThreshold`	`integer`
`memoryThreshold`	`integer`
`hysteresis`	`integer`
`maxQueueWaitMinutes`	`integer \| null`
`autoPauseIdleBoxes`	`boolean`
`busyIdleMinutes`	`integer`

RunnerQueue

Fields

Name	Type	Description
`host`	`object \| null`
`entries`	`RunnerQueueEntry[]`

RunnerQueueEntry

Fields

Name	Type	Description
`chatId`	`string \| null`
`workspace`	`object`
`container`	`object \| null`
`owner`	`object \| null`
`state`	`"running" \| "queued" \| "held" \| "failed"`
`reason`	`"concurrency" \| "load" \| "usage" \| null`
`position`	`integer \| null`
`mode`	`"chat" \| "spec-draft" \| "implement" \| null`
`error`	`string \| null`
`since`	`string \| null`

RunnerReleases

Fields

Name	Type	Description
`latest`	`object \| null`
`installScript`	`object`
`composeFile`	`string`

RunnerUpdateStarted

Fields

Name	Type	Description
`from`	`string`
`to`	`string`
`restart`	`"service" \| "container" \| "self"`

SaveHistoryBody

Fields

Name	Type	Description
`message`optional	`string`
`container`optional	`string`

Screenshot

Fields

Name	Type	Description
`path`	`string`
`width`	`integer`
`height`	`integer`
`warnings`	`string[]`
`blockId`	`string \| null`

ScreenshotBody

Fields

Name	Type	Description
`container`optional	`string`
`mode`	`"url" \| "screen"`
`url`optional	`string`
`width`optional	`integer`
`height`optional	`integer`
`fullPage`optional	`boolean`
`addToCanvas`optional	`boolean`

SendChatBody

Fields

Name	Type	Description
`text`	`string`
`contextBlockIds`optional	`string[]`
`sheetId`optional	`string \| null`
`attachments`optional	`string[]`
`provider`optional	`"claude" \| "codex" \| "cursor" \| "fake"`
`model`optional	`string`
`effort`optional	`string`

SetPatBody

Fields

Name	Type	Description
`token`	`string`

SetRepoBranchBody

Fields

Name	Type	Description
`branch`	`string`

SetRepoReadOnlyBody

Fields

Name	Type	Description
`readOnly`	`boolean`

SetRunnerDirectBody

Fields

Name	Type	Description
`url`	`string`

SetShareRoleBody

Fields

Name	Type	Description
`role`	`"editor" \| "viewer" \| null`

SetSheetMemberBody

Fields

Name	Type	Description
`role`	`"editor" \| "viewer"`

SetWorkspaceLogoBody

object | object

ShareInviteBody

Fields

Name	Type	Description
`email`	`string`
`role`optional	`"editor" \| "viewer"`

ShareInviteResult

Fields

Name	Type	Description
`outcome`	`"granted" \| "invited"`
`url`	`string \| null`

ShareMember

Fields

Name	Type	Description
`userId`	`string`
`name`	`string`
`email`	`string`
`orgRole`	`"owner" \| "admin" \| "member"`
`role`	`"owner" \| "editor" \| "viewer" \| null`
`explicit`	`boolean`

Sheet

Fields

Name	Type	Description
`id`	`string \| null`
`name`	`string`
`docId`	`string`
`access`	`"workspace" \| "restricted"`
`role`	`"owner" \| "editor" \| "viewer"`
`canManage`	`boolean`
`createdBy`	`object \| null`

SheetList

Fields

Name	Type	Description
`sheets`	`Sheet[]`

SheetMember

Fields

Name	Type	Description
`userId`	`string`
`name`	`string`
`email`	`string`
`role`	`"editor" \| "viewer"`

SheetMembers

Fields

Name	Type	Description
`access`	`"workspace" \| "restricted"`
`members`	`SheetMember[]`

SignInBody

Fields

Name	Type	Description
`email`	`string`
`password`	`string`

SignUpBody

Fields

Name	Type	Description
`email`	`string`
`password`	`string`
`name`	`string`

SnapshotLink

Fields

Name	Type	Description
`url`	`string \| null`
`lastSyncedAt`	`string \| null`

StartAgentLoginBody

Fields

Name	Type	Description
`runnerId`optional	`string`

StartContainerBody

Fields

Name	Type	Description
`provider`optional	`"claude" \| "codex" \| "cursor" \| "fake"`
`model`optional	`string`
`effort`optional	`string`

StartThreadBody

Fields

Name	Type	Description
`container`optional	`string`
`anchor`	`object \| object`
`body`	`string`

StorageBucket

Fields

Name	Type	Description
`id`	`string`
`scope`	`"instance" \| "org"`
`name`	`string`
`provider`	`"r2" \| "s3" \| "gcs" \| "s3c"`
`isDefault`	`boolean`
`acceptsNew`	`boolean`
`source`	`"env" \| "legacy" \| "added"`
`endpoint`	`string \| null`
`region`	`string \| null`
`bucket`	`string \| null`
`accessKeyId`	`string \| null`
`hasSecret`	`boolean`
`workspaces`	`integer \| null`

StorageTestResult

Fields

Name	Type	Description
`ok`	`boolean`
`step`	`string \| null`
`detail`	`string \| null`

SttStatus

Fields

Name	Type	Description
`available`	`boolean`
`source`	`"account" \| "org" \| null`

SyncBackResult

Fields

Name	Type	Description
`copied`	`integer`
`merged`	`integer`
`conflicts`	`FileConflict[]`

Terminal

Fields

Name	Type	Description
`id`	`string`
`container`	`string \| null`
`title`	`string`

TotpCodeBody

Fields

Name	Type	Description
`code`	`string`

TotpSetup

Fields

Name	Type	Description
`secret`	`string`
`otpauthUrl`	`string`

TranscribeBody

Fields

Name	Type	Description
`audio`	`string`
`mimeType`optional	`string`
`org`optional	`string`

Transcription

Fields

Name	Type	Description
`text`	`string`

TransferBody

Fields

Name	Type	Description
`from`	`object`
`to`	`object`
`dir`optional	`string`
`move`optional	`boolean`

TransferResult

Fields

Name	Type	Description
`path`	`string`
`files`	`integer`
`merged`optional	`integer`
`conflicts`optional	`FileConflict[]`

TwoFactorChallenge

Fields

Name	Type	Description
`twoFactor`	`object`

TwoFactorEmailSendBody

Fields

Name	Type	Description
`challengeId`	`string`

TwoFactorPreferredBody

Fields

Name	Type	Description
`method`	`"totp" \| "passkey" \| "email"`

TwoFactorVerifyBody

Fields

Name	Type	Description
`challengeId`	`string`
`code`	`string`

UnarchiveBody

Fields

Name	Type	Description
`runnerId`optional	`string`

UpdateAdminUserBody

Fields

Name	Type	Description
`isAdmin`optional	`boolean`
`disabled`optional	`boolean`

UpdateContainerBody

Fields

Name	Type	Description
`title`	`string`

UpdateMemberBody

Fields

Name	Type	Description
`role`	`"owner" \| "admin" \| "member"`

UpdateOrgBody

Fields

Name	Type	Description
`name`optional	`string`
`slug`optional	`string`
`retentionDays`optional	`0 \| 3 \| 7 \| 14 \| 30 \| 90 \| 365`
`defaultAgent`optional	`string \| null`
`defaultModel`optional	`string \| null`
`defaultEffort`optional	`string \| null`
`allowedEmailDomains`optional	`string[]`

UpdateOrgStorageBody

Fields

Name	Type	Description
`kind`	`"managed" \| "r2" \| "s3" \| "gcs"`
`endpoint`optional	`string`
`region`optional	`string`
`bucket`optional	`string`
`accessKeyId`optional	`string`
`secretAccessKey`optional	`string`

UpdatePersonalRunnerBody

Fields

Name	Type	Description
`othersCanEdit`optional	`boolean`
`agentConcurrency`optional	`integer \| null`
`load`optional	`RunnerLoadPatch`

UpdateProfileBody

Fields

Name	Type	Description
`name`	`string`

UpdateRunnerBody

Fields

Name	Type	Description
`agentConcurrency`optional	`integer \| null`
`load`optional	`RunnerLoadPatch`

UpdateSheetBody

Fields

Name	Type	Description
`name`optional	`string`
`position`optional	`integer`
`access`optional	`"workspace" \| "restricted"`

UpdateStorageBucketBody

Fields

Name	Type	Description
`name`optional	`string`
`isDefault`optional	`boolean`
`acceptsNew`optional	`boolean`
`accessKeyId`optional	`string`
`secretAccessKey`optional	`string`

UpdateWorkspaceBody

Fields

Name	Type	Description
`name`optional	`string`
`runnerId`optional	`string`
`orgAccess`optional	`"edit" \| "view" \| "none"`
`defaultAgent`optional	`string \| null`
`defaultModel`optional	`string \| null`
`defaultEffort`optional	`string \| null`
`useGpu`optional	`boolean`
`deleteWorktreesWhenDone`optional	`boolean`
`autoApproveSpec`optional	`boolean`
`autoPush`optional	`boolean`
`autoOpenPr`optional	`boolean`
`limits`optional	`WorkspaceLimits`
`historyRemote`optional	`string \| null`

UploadResult

Fields

Name	Type	Description
`path`	`string`
`size`	`number`

UploadTicket

Fields

Name	Type	Description
`id`	`string`
`mode`	`"bucket" \| "relay"`
`url`	`string`
`path`	`string`

User

Fields

Name	Type	Description
`id`	`string`
`email`	`string`
`name`	`string`
`emailVerified`	`boolean`
`isAdmin`	`boolean`
`twoFactor`	`object`
`createdAt`	`string`

UserResponse

Fields

Name	Type	Description
`user`	`User`

VerifyBody

Fields

Name	Type	Description
`code`	`string`

Workspace

Fields

Name	Type	Description
`id`	`string`
`orgId`	`string`
`slug`	`string`
`name`	`string`
`status`	`"provisioning" \| "ready" \| "error" \| "archived"`
`error`	`string \| null`
`runner`	`WorkspaceRunner`
`role`	`"owner" \| "editor" \| "viewer"`
`orgAccess`	`"edit" \| "view" \| "none"`
`defaultAgent`	`string \| null`
`defaultModel`	`string \| null`
`defaultEffort`	`string \| null`
`useGpu`	`boolean`
`deleteWorktreesWhenDone`	`boolean`
`autoApproveSpec`	`boolean`
`autoPush`	`boolean`
`autoOpenPr`	`boolean`
`limits`	`WorkspaceLimits`
`historyRemote`	`string \| null`
`logo`	`string \| null`
`logoSource`	`"github" \| "upload" \| "file" \| null`
`logoRef`	`string \| null`
`blockCount`	`integer`
`repoCount`	`integer`
`containerCount`	`integer`
`agentWorking`	`boolean`
`head`	`string \| null`
`lastSyncedAt`	`string \| null`
`storageConnected`	`boolean`
`archivedAt`	`string \| null`
`updatedAt`	`string`
`createdAt`	`string`

WorkspaceAppsSettings

Fields

Name	Type	Description
`hosterId`	`string \| null`
`hosters`	`object[]`

WorkspaceLimits

Fields

Name	Type	Description
`cpus`	`number \| null`
`memoryMb`	`integer \| null`

WorkspaceRepo

Fields

Name	Type	Description
`repo`	`Repo`
`status`	`"cloning" \| "ready" \| "error"`
`state`	`"cloning" \| "fetching" \| "ready" \| "error" \| "offline"`
`error`	`string \| null`
`errorAt`	`string \| null`
`checkedAt`	`string \| null`
`head`	`string \| null`
`branch`	`string`
`readOnly`	`boolean`

WorkspaceRunner

Fields

Name	Type	Description
`id`	`string`
`name`	`string`
`kind`	`"official" \| "official-pro" \| "org" \| "personal"`
`online`	`boolean`
`lastSeenAt`	`string \| null`
`gpu`	`boolean`
`personal`	`object \| null`

WorkspaceStorage

Fields

Name	Type	Description
`bucket`	`StorageBucket & object \| null`
`migration`	`object \| null`
`choices`	`StorageBucket[]`

WorkspaceUsage

Fields

Name	Type	Description
`supported`	`boolean`
`measuredAt`	`string`
`boxes`	`object[]`
`gpu`	`object[]`
`disk`	`object`
`limits`	`WorkspaceLimits`

WriteFileBody

Fields

Name	Type	Description
`content`	`string`
`base`optional	`string`

WriteFileResult

Fields

Name	Type	Description
`ok`	`true`
`merged`	`boolean`
`conflict`	`FileConflict`

API reference

Base address

Authenticating

Scopes

Limits

Errors

Health

GET /v1/health

Auth

POST /v1/auth/signup

POST /v1/auth/signin

POST /v1/auth/signout

GET /v1/auth/me

PATCH /v1/auth/me

POST /v1/auth/verify

POST /v1/auth/verify/resend

PUT /v1/auth/password

GET /v1/auth/providers

POST /v1/auth/github/url

GET /v1/auth/github/signup

POST /v1/auth/github/signup

POST /v1/auth/2fa/totp/setup

POST /v1/auth/2fa/totp/enable

POST /v1/auth/2fa/totp/disable

POST /v1/auth/2fa/verify

POST /v1/auth/2fa/email/send

POST /v1/auth/2fa/email/setup

POST /v1/auth/2fa/email/enable

POST /v1/auth/2fa/email/disable

PUT /v1/auth/2fa/preferred

GET /v1/auth/passkeys

POST /v1/auth/passkeys/register/options

POST /v1/auth/passkeys/register/verify

DELETE /v1/auth/passkeys/{id}

POST /v1/auth/passkeys/login/options

POST /v1/auth/passkeys/login/verify

Orgs

GET /v1/orgs

POST /v1/orgs

GET /v1/orgs/{org}

PATCH /v1/orgs/{org}

DELETE /v1/orgs/{org}

GET /v1/orgs/{org}/members

PATCH /v1/orgs/{org}/members/{userId}

DELETE /v1/orgs/{org}/members/{userId}

API keys

GET /v1/me/api-keys

POST /v1/me/api-keys

DELETE /v1/me/api-keys/{id}

POST /v1/me/api-keys/{id}/rotate

GET /v1/orgs/{org}/api-keys

POST /v1/orgs/{org}/api-keys

DELETE /v1/orgs/{org}/api-keys/{id}

POST /v1/orgs/{org}/api-keys/{id}/rotate

CLI sign-in

POST /v1/cli/login/start

POST /v1/cli/login/poll

GET /v1/cli/login/{code}

POST /v1/cli/login/{code}/approve

POST /v1/cli/login/{code}/deny

POST /v1/cli/logout

Invites

GET /v1/orgs/{org}/invites

POST /v1/orgs/{org}/invites

DELETE /v1/orgs/{org}/invites/{id}

GET /v1/invites/{token}

POST /v1/invites/{token}/accept

Runners

GET /v1/orgs/{org}/runners

POST /v1/orgs/{org}/runners

PATCH /v1/orgs/{org}/runners/{id}

DELETE /v1/orgs/{org}/runners/{id}

POST /v1/orgs/{org}/runners/{id}/rotate-token

POST /v1/admin/runners/{id}/rotate-token

POST /v1/orgs/{org}/runners/{id}/device/approve

POST /v1/admin/runners/{id}/device/approve

POST /v1/orgs/{org}/runners/{id}/device/reject

POST /v1/admin/runners/{id}/device/reject

POST /v1/orgs/{org}/runners/{id}/device/reset

POST /v1/admin/runners/{id}/device/reset

GET `/v1/health`

POST `/v1/auth/signup`

POST `/v1/auth/signin`

POST `/v1/auth/signout`

GET `/v1/auth/me`

PATCH `/v1/auth/me`

POST `/v1/auth/verify`

POST `/v1/auth/verify/resend`

PUT `/v1/auth/password`

GET `/v1/auth/providers`

POST `/v1/auth/github/url`

GET `/v1/auth/github/signup`

POST `/v1/auth/github/signup`

POST `/v1/auth/2fa/totp/setup`

POST `/v1/auth/2fa/totp/enable`

POST `/v1/auth/2fa/totp/disable`

POST `/v1/auth/2fa/verify`

POST `/v1/auth/2fa/email/send`

POST `/v1/auth/2fa/email/setup`

POST `/v1/auth/2fa/email/enable`

POST `/v1/auth/2fa/email/disable`

PUT `/v1/auth/2fa/preferred`

GET `/v1/auth/passkeys`

POST `/v1/auth/passkeys/register/options`

POST `/v1/auth/passkeys/register/verify`

DELETE `/v1/auth/passkeys/{id}`

POST `/v1/auth/passkeys/login/options`

POST `/v1/auth/passkeys/login/verify`

GET `/v1/orgs`

POST `/v1/orgs`

GET `/v1/orgs/{org}`

PATCH `/v1/orgs/{org}`

DELETE `/v1/orgs/{org}`

GET `/v1/orgs/{org}/members`

PATCH `/v1/orgs/{org}/members/{userId}`

DELETE `/v1/orgs/{org}/members/{userId}`

GET `/v1/me/api-keys`

POST `/v1/me/api-keys`

DELETE `/v1/me/api-keys/{id}`

POST `/v1/me/api-keys/{id}/rotate`

GET `/v1/orgs/{org}/api-keys`

POST `/v1/orgs/{org}/api-keys`

DELETE `/v1/orgs/{org}/api-keys/{id}`

POST `/v1/orgs/{org}/api-keys/{id}/rotate`

POST `/v1/cli/login/start`

POST `/v1/cli/login/poll`

GET `/v1/cli/login/{code}`

POST `/v1/cli/login/{code}/approve`

POST `/v1/cli/login/{code}/deny`

POST `/v1/cli/logout`

GET `/v1/orgs/{org}/invites`

POST `/v1/orgs/{org}/invites`

DELETE `/v1/orgs/{org}/invites/{id}`

GET `/v1/invites/{token}`

POST `/v1/invites/{token}/accept`

GET `/v1/orgs/{org}/runners`

POST `/v1/orgs/{org}/runners`

PATCH `/v1/orgs/{org}/runners/{id}`

DELETE `/v1/orgs/{org}/runners/{id}`

POST `/v1/orgs/{org}/runners/{id}/rotate-token`

POST `/v1/admin/runners/{id}/rotate-token`

POST `/v1/orgs/{org}/runners/{id}/device/approve`

POST `/v1/admin/runners/{id}/device/approve`

POST `/v1/orgs/{org}/runners/{id}/device/reject`

POST `/v1/admin/runners/{id}/device/reject`

POST `/v1/orgs/{org}/runners/{id}/device/reset`

POST `/v1/admin/runners/{id}/device/reset`

PUT `/v1/orgs/{org}/runners/{id}/direct`

DELETE `/v1/orgs/{org}/runners/{id}/direct`

POST `/v1/orgs/{org}/runners/{id}/direct/verify`

GET `/v1/me/runners`

POST `/v1/me/runners`

PATCH `/v1/me/runners/{id}`

DELETE `/v1/me/runners/{id}`

POST `/v1/me/runners/{id}/rotate-token`

POST `/v1/me/runners/{id}/device/approve`

POST `/v1/me/runners/{id}/device/reject`

POST `/v1/me/runners/{id}/device/reset`

PUT `/v1/me/runners/{id}/direct`

DELETE `/v1/me/runners/{id}/direct`