--- title: "Organisation · API reference · Promigence" description: "The Promigence API's organisation routes: 24 in all, with parameters, request bodies and answers." url: "https://www.promigence.ai/docs/reference/api/organisation" site: "Promigence" --- [API reference](https://www.promigence.ai/docs/reference/api) # Organisation 24 routes of the published API contract, generated from it. ### 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=&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 ` 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 ` 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 [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)