Organisation

GET/v1/invites

Auth: sign-in token

Invites waiting for your verified email address, from any organization. Needs a sign-in.

Answer 200 · InviteList · application/json

invitesrequiredInviteView[]

POST/v1/invites/{invite_id}/accept

Auth: sign-in token

Accept an invite and join the organization. Needs a sign-in: the identity token's own verified email must be the invited address, and the member who sent it must still be an owner.

Parameters

invite_idrequiredpath · string

Answer 200 · OrgView · application/json

card_on_filerequiredboolean

A payment method is on file.

created_atrequiredstring

RFC 3339.

defaultrequiredboolean

True for the organization a sign-in and the CLI use when none is named.

membersrequiredinteger

namerequiredstring

org_idrequiredstring

projectsrequiredinteger

rolerequiredstring

Your role in it: owner or member.

POST/v1/invites/{invite_id}/decline

Auth: sign-in token

Decline an invite sent to your verified email address. It is gone for good, and the organization may invite the address again.

Parameters

invite_idrequiredpath · string

Answer 200 · InviteRevoked · application/json

invite_idrequiredstring

revokedrequiredboolean

GET/v1/me

Auth: API key

Who you are, what your limits are, what you have spent, and what trial credit is left.

Answer 200 · Me · application/json

card_on_filerequiredboolean

concurrencyMeConcurrency

Live sandboxes now, against the organisation's limit.

default_spend_caprequirednumber

The cap a run gets when it names none, in USD.

keyKeyRef | null

The key this request was made with.

limitsrequiredMeLimits

The limits in force for an organisation.

locationstring | null

Where sandboxes run, in plain words (for example "US East Coast"), as GET /v1/health says it. Absent when the service does not say.

location_codestring | null

The same place as a short code, for example us-east. Only beside location; new codes may appear, and a code you do not know is fine to ignore.

noticeTrialNotice | null

A notice about a coming change to the trial rules; null when there is none.

orgrequiredstring

The organisation's name.

org_idrequiredstring

planstring

The plan the organisation's limits and prices come from: hobby for a trial organisation with no plan assigned.

spendnumber | null

What the organisation has spent, in USD. Absent for a key that may not see the organisation's money (see trial).

spend_detailSpendDetail | null

trialTrialStatus | null

The organisation's trial credit. Absent for a key that may not see the organisation's money: only an owner's key of the default project does.

userUserView | null

The user behind the key this request was made with; null for a key minted by an operator.

GET/v1/me/ledger

Auth: API key

The rows behind spend: usage recorded while each sandbox runs and when it ends. With a project's key, that project's rows and the organization's credit grants; spend stays the organization's. ?limit=N.

Parameters

cursorquery · string

limitquery · integer

Answer 200 · LedgerList · application/json

entriesrequiredLedgerEntryView[]

Newest first.

next_cursorstring | null

Pass as ?cursor= for the next page; null on the last one.

GET/v1/me/outcomes

Auth: API key

What the organization got this month, measured from its own runs and sandboxes: runs and sandboxes started, the median time to ready, failures on our side that were not billed and what was given back, hours paused and what they would have cost running, failed sandboxes kept to reopen, and for runs of two or more sandboxes how many times faster than one after another and the time not spent waiting. With a project's key, that project's. A figure with nothing behind it is null. ?period=month.

Parameters

periodquery · string

Answer 200 · Outcomes · application/json

batch_runsrequiredinteger

Finished runs of two or more sandboxes this period.

batch_saved_snumber | null

For those runs: seconds not spent waiting, the sum of their sandboxes' own times minus the runs' wall time; null without such a run.

batch_speedupnumber | null

For those runs: the sum of their sandboxes' own times divided by the runs' wall time (how many times faster than one after another); null without such a run.

failures_oursrequiredinteger

Sandboxes that ended on a failure on our side and were not billed for it.

failures_ours_usdrequirednumber

What was given back for those failures, in USD (0 when they ended before any charge).

kept_failuresrequiredinteger

Failed sandboxes kept to reopen that can still be reopened.

paused_hoursnumber | null

Hours this period's sandboxes spent paused, which is not billed; null if none paused.

paused_usdnumber | null

What those paused hours would have cost running, in USD; null if none paused.

periodrequiredstring

month: the calendar month so far, UTC.

ready_ms_p50number | null

The median milliseconds until a sandbox was ready to take work; null with no sandbox.

runsrequiredinteger

Runs started this period.

sandboxesrequiredinteger

Sandboxes started this period.

sincerequiredstring

When the period began (RFC 3339, UTC).

GET/v1/orgs

Auth: API key

The organizations you belong to, your role in each, and which one is your default. With an API key, only that key's own organization; a sign-in lists every one.

Answer 200 · OrgList · application/json

orgsrequiredOrgView[]

POST/v1/orgs

Auth: sign-in token

Create an organization. You become its owner and it starts with a default project. It gets no trial credit — the trial belongs to the person — so add a card before its first run.

Request body NameCreate · application/json

namerequiredstring

1–40 lowercase letters, digits and dashes.

Answer 201 · OrgView · application/json

card_on_filerequiredboolean

A payment method is on file.

created_atrequiredstring

RFC 3339.

defaultrequiredboolean

True for the organization a sign-in and the CLI use when none is named.

membersrequiredinteger

namerequiredstring

org_idrequiredstring

projectsrequiredinteger

rolerequiredstring

Your role in it: owner or member.

PATCH/v1/orgs/{org}

Auth: API key

Rename an organization. Owners only. Its id never changes; anything that names it by the old name (a script, --org, a saved URL) must use the new one. The same rules as a new name: free, and not starting with promigence.

Parameters

orgrequiredpath · string

Request body OrgPatch · application/json

namerequiredstring

1–40 lowercase letters, digits and dashes.

Answer 200 · OrgView · application/json

card_on_filerequiredboolean

A payment method is on file.

created_atrequiredstring

RFC 3339.

defaultrequiredboolean

True for the organization a sign-in and the CLI use when none is named.

membersrequiredinteger

namerequiredstring

org_idrequiredstring

projectsrequiredinteger

rolerequiredstring

Your role in it: owner or member.

DELETE/v1/orgs/{org}

Auth: API key

Delete an organization. Its keys stop working, pending invites are revoked and every member leaves it; a member for whom it was the only organization gets a fresh personal one (no trial credit). Owners only, signed in. Refused while it is suspended, has a subscription (cancel it in the billing portal first), a snapshot, a build running, a failure capture or a sandbox that has not ended (a paused one included). Its secrets are deleted, the commands and output of its runs and builds and the data stored for it are erased, and its name is freed; invoices, the billing ledger and the audit log are kept.

Parameters

orgrequiredpath · string

Request body OrgDelete · application/json

confirmrequiredstring

The organization's name, typed out.

Answer 200 · OrgDeleted · application/json

deletedrequiredboolean

keys_revokedrequiredinteger

Keys that stopped working (every key of the organization).

members_rehomedrequiredinteger

Members it was the last organization of, each given a fresh personal one.

org_idrequiredstring

GET/v1/orgs/{org}/audit

Auth: API key

The organization's audit log, newest first: keys minted and revoked, invites, role changes, removals, projects, billing events, suspension, and what support did to the organization (shown as Promigence support). Owners only, signed in. ?before=<seq>&limit= (at most 100) pages back.

Parameters

orgrequiredpath · string

beforequery · integer

limitquery · integer

Answer 200 · AuditList · application/json

entriesrequiredAuditEntry[]

org_idrequiredstring

POST/v1/orgs/{org}/default

Auth: API key

Make this organization the one a sign-in and the CLI use when none is named.

Parameters

orgrequiredpath · string

Answer 200 · OrgView · application/json

card_on_filerequiredboolean

A payment method is on file.

created_atrequiredstring

RFC 3339.

defaultrequiredboolean

True for the organization a sign-in and the CLI use when none is named.

membersrequiredinteger

namerequiredstring

org_idrequiredstring

projectsrequiredinteger

rolerequiredstring

Your role in it: owner or member.

GET/v1/orgs/{org}/invites

Auth: API key

Pending invites to an organization. An invite nobody accepts is gone after 14 days.

Parameters

orgrequiredpath · string

Answer 200 · InviteList · application/json

invitesrequiredInviteView[]

POST/v1/orgs/{org}/invites

Auth: API key

Invite an email address. Owners only, signed in (not with a key). Only a signed-in user whose verified email is that address can accept it.

Parameters

orgrequiredpath · string

Request body InviteCreate · application/json

emailrequiredstring

rolestring | null

owner or member (default).

Answer 201 · InviteView · application/json

created_atrequiredstring

RFC 3339.

emailrequiredstring

The address invited. Only a signed-in user whose verified email is this address can accept it.

invite_idrequiredstring

invited_byrequiredstring

The verified email of the owner who sent it, or An owner of <org> when that address is not verified.

org_idrequiredstring

org_namerequiredstring

rolerequiredstring

owner or member.

DELETE/v1/orgs/{org}/invites/{invite_id}

Auth: API key

Revoke a pending invite. Owners only, signed in.

Parameters

orgrequiredpath · string

invite_idrequiredpath · string

Answer 200 · InviteRevoked · application/json

invite_idrequiredstring

revokedrequiredboolean

POST/v1/orgs/{org}/invites/{invite_id}/resend

Auth: API key

Send a pending invite's email again: the same invite, its 14 days counted again from now. Owners only. At most once every 10 minutes and three times a day per invite.

Parameters

orgrequiredpath · string

invite_idrequiredpath · string

Answer 200 · InviteView · application/json

created_atrequiredstring

RFC 3339.

emailrequiredstring

The address invited. Only a signed-in user whose verified email is this address can accept it.

invite_idrequiredstring

invited_byrequiredstring

The verified email of the owner who sent it, or An owner of <org> when that address is not verified.

org_idrequiredstring

org_namerequiredstring

rolerequiredstring

owner or member.

GET/v1/orgs/{org}/members

Auth: API key

The members of an organization and their roles.

Parameters

orgrequiredpath · string

Answer 200 · MemberList · application/json

membersrequiredMemberView[]

org_idrequiredstring

PATCH/v1/orgs/{org}/members/{user_id}

Auth: API key

Change a member's role. Owners only, signed in (not with a key); an organization always keeps at least one owner.

Parameters

orgrequiredpath · string

user_idrequiredpath · string

Request body MemberRoleSet · application/json

rolerequiredstring

owner or member.

Answer 200 · MemberList · application/json

membersrequiredMemberView[]

org_idrequiredstring

DELETE/v1/orgs/{org}/members/{user_id}

Auth: API key

Remove a member (owners, signed in), or leave (your own user id, or me). The keys that person minted for themselves in the organization are revoked; service keys keep working. The last owner cannot leave, and nobody can leave their only organization; an owner removing someone from theirs gives them a fresh personal organization (no trial credit).

Parameters

orgrequiredpath · string

user_idrequiredpath · string

Answer 200 · MemberRemoved · application/json

keys_revokedrequiredinteger

Keys that person had minted for themselves in this organization, now revoked. Service keys keep working.

org_idrequiredstring

removedrequiredboolean

user_idrequiredstring

GET/v1/orgs/{org}/projects

Auth: API key

An organization's projects, each with what it was billed this calendar month (UTC): month and month_spend_usd, the figure its monthly cap is checked against. ?month=YYYY-MM gives another month. API keys belong to a project; a project holds any number of repositories.

Parameters

orgrequiredpath · string

monthquery · string

Answer 200 · ProjectList · application/json

org_idrequiredstring

projectsrequiredProjectView[]

POST/v1/orgs/{org}/projects

Auth: API key

Create a project.

Parameters

orgrequiredpath · string

Request body NameCreate · application/json

namerequiredstring

1–40 lowercase letters, digits and dashes.

Answer 201 · ProjectView · application/json

created_atrequiredstring

RFC 3339.

defaultrequiredboolean

True for the project every organization starts with. It cannot be renamed or deleted.

keysrequiredinteger

Keys that still work.

monthstring | null

The calendar month (UTC, YYYY-MM) month_spend_usd is for: this month, or the one a list asked for with ?month=.

month_spend_usdnumber | null

What this project's runs, data out and builds were billed in month, in USD: the same figure its monthly cap is checked against.

monthly_cap_usdnumber | null

The most this project's runs may bill in one calendar month (UTC), in USD; null = no cap. A run that would pass it is refused with project_cap_reached. Set by an owner.

namerequiredstring

org_idrequiredstring

project_idrequiredstring

PATCH/v1/orgs/{org}/projects/{project}

Auth: API key

Rename a project, set its monthly cap, or both. The default project keeps its name. The cap is the most the project may be billed in one calendar month (UTC) — its sandboxes, their data out and its builds — counting what its live sandboxes could still bill; a create, replay, open or extension past it is refused with project_cap_reached and nothing starts. Setting the cap is for owners, signed in (not with a key).

Parameters

orgrequiredpath · string

projectrequiredpath · string

Request body ProjectPatch · application/json · optional

monthly_cap_usdnumber | null

A monthly spending cap in USD, 0–1000000; null removes the cap.

namestring | null

Answer 200 · ProjectView · application/json

created_atrequiredstring

RFC 3339.

defaultrequiredboolean

True for the project every organization starts with. It cannot be renamed or deleted.

keysrequiredinteger

Keys that still work.

monthstring | null

The calendar month (UTC, YYYY-MM) month_spend_usd is for: this month, or the one a list asked for with ?month=.

month_spend_usdnumber | null

What this project's runs, data out and builds were billed in month, in USD: the same figure its monthly cap is checked against.

monthly_cap_usdnumber | null

The most this project's runs may bill in one calendar month (UTC), in USD; null = no cap. A run that would pass it is refused with project_cap_reached. Set by an owner.

namerequiredstring

org_idrequiredstring

project_idrequiredstring

DELETE/v1/orgs/{org}/projects/{project}

Auth: API key

Delete a project with no working keys, no snapshots, no builds running, no failure captures and no sandbox that has not ended. Its secrets go with it; its past runs move to the default project. Owners only, signed in; never the default project.

Parameters

orgrequiredpath · string

projectrequiredpath · string

Answer 200 · ProjectDeleted · application/json

deletedrequiredboolean

project_idrequiredstring

POST/v1/orgs/{org}/projects/{project}/move

Auth: API key

Move a project to another organization: its snapshots and secrets go with it, its past runs stay with the organization that paid for them, in its default project, and every key of the project is revoked (mint new ones there). Owners of the source only, signed in; you must belong to the target, and the target must have a card on file. Refused for the default project, a name the target already uses, or while any of the project's sandboxes has not ended, a build is running or a failure capture is left.

Parameters

orgrequiredpath · string

projectrequiredpath · string

Request body ProjectMove · application/json

torequiredstring

The target organization's id or name.

Answer 200 · ProjectMoved · application/json

from_org_idrequiredstring

keys_revokedrequiredinteger

project_idrequiredstring

secrets_movedrequiredinteger

snapshots_movedrequiredinteger

to_org_idrequiredstring