---
title: "API reference · Promigence"
description: "Every route of the Promigence REST API: snapshots, runs, sandboxes, commands, files, terminals, secrets, organisations, billing and keys, with parameters, request bodies and answers."
url: "https://www.promigence.ai/docs/reference/api"
site: "Promigence"
---

# API reference

The 129 routes of the published API contract, generated from it. The CLI and the TypeScript SDK call the same routes, so anything you can do from them you can do over HTTP.

## Basics

- Base URL: `https://api.promigence.ai`. Requests and answers are JSON unless a route says otherwise.
- Authentication: `Authorization: Bearer <API key>`. Create a key with `promigence keys create` or in the console; `promigence login` stores one for the CLI and the SDK.
- Errors: an answer that is not a success carries `{"error": {...}}` with a stable `code`, a `message`, a `fix`, the CLI `exit` code, its `category`, `retryable` and a `request_id`. [Every error code](https://www.promigence.ai/docs/errors)
- Retries: send an `Idempotency-Key` header with a create, and a retry of the same request starts, and bills, once.
- The contract itself, the document this page is generated from, as OpenAPI 3.1 for client generators and tools: [/openapi.json](https://www.promigence.ai/openapi.json)

Two sandboxes, one command each, capped at $1

bash

```
curl -s https://api.promigence.ai/v1/runs \
  -H "Authorization: Bearer $PROMIGENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"snapshot": "promigence/base", "count": 2, "spend_cap": 1, "exec": {"sh": "python3 -c \"print(6*7)\""}}'
```

## Meta

[All 4 in full](https://www.promigence.ai/docs/reference/api/meta)

- [GET /status The same data rendered as a self-contained HTML page by the API itself.](https://www.promigence.ai/docs/reference/api/meta#get-status)
- [GET /v1/health Liveness, and whether the service can start sandboxes.](https://www.promigence.ai/docs/reference/api/meta#get-v1-health)
- [GET /v1/llms.txt The agent guide as text/plain — the same document promigence agent-guide prints.](https://www.promigence.ai/docs/reference/api/meta#get-v1-llms-txt)
- [GET /v1/status 24 hours of synthetic check results plus service health, as JSON.](https://www.promigence.ai/docs/reference/api/meta#get-v1-status)

## Snapshots

[All 13 in full](https://www.promigence.ai/docs/reference/api/snapshots)

- [POST /v1/images/resolve Turn an image tag into a digest.](https://www.promigence.ai/docs/reference/api/snapshots#post-v1-images-resolve)
- [GET /v1/snapshots List snapshots, newest first.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots)
- [POST /v1/snapshots Build and verify a snapshot.](https://www.promigence.ai/docs/reference/api/snapshots#post-v1-snapshots)
- [GET /v1/snapshots/{id} One snapshot by id or alias.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-id)
- [DELETE /v1/snapshots/{id} Remove one of your own snapshots from your catalogue.](https://www.promigence.ai/docs/reference/api/snapshots#delete-v1-snapshots-id)
- [PUT /v1/snapshots/{id}/alias Move the snapshot's alias.](https://www.promigence.ai/docs/reference/api/snapshots#put-v1-snapshots-id-alias)
- [GET /v1/snapshots/{id}/manifest The manifest: what a .promigence bundle is built from.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-id-manifest)
- [POST /v1/snapshots/{id}/verify Re-run the snapshot's own verify command in a fresh fork.](https://www.promigence.ai/docs/reference/api/snapshots#post-v1-snapshots-id-verify)
- [GET /v1/snapshots/builds List your org's builds.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-builds)
- [GET /v1/snapshots/builds/{id} One build. ?wait_ms=N long-polls until the build reaches a terminal state, capped at 30 s server-side.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-builds-id)
- [GET /v1/snapshots/builds/{id}/build-log The tail of the build log.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-builds-id-build-log)
- [GET /v1/templates The templates: ready-made starting points to fork (languages, app starters, agent tools, benchmarks).](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-templates)
- [GET /v1/templates/{name} One template: its setup steps, everything it has installed (each package and its version, by package manager, and each tool's version), and every version with what changed.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-templates-name)

## GitHub

[All 7 in full](https://www.promigence.ai/docs/reference/api/github)

- [GET /v1/integrations/github Your organization's GitHub connections, the ones still being finished, and the snapshots that follow a branch.](https://www.promigence.ai/docs/reference/api/github#get-v1-integrations-github)
- [POST /v1/integrations/github/connect Start connecting a GitHub account: a link to install the platform's GitHub App on it, valid for 15 minutes.](https://www.promigence.ai/docs/reference/api/github#post-v1-integrations-github-connect)
- [DELETE /v1/integrations/github/installations/{installation_id} Disconnect a GitHub account: nothing is built from it any more and the snapshots that followed its branches stop following them.](https://www.promigence.ai/docs/reference/api/github#delete-v1-integrations-github-installations-installation-id)
- [GET /v1/integrations/github/repos The repositories your GitHub connections can read, one page at a time ( page , per_page up to 100).](https://www.promigence.ai/docs/reference/api/github#get-v1-integrations-github-repos)
- [POST /v1/integrations/github/requests Start connecting a GitHub account in the console, for yourself: a one-time ticket (5 minutes) and the console page that uses it ( connect_url ).](https://www.promigence.ai/docs/reference/api/github#post-v1-integrations-github-requests)
- [GET /v1/integrations/github/requests/{request_id} How a GitHub connection request you started ended: pending , then connected , updated (already connected; its repository access changed), pending_provider_approval (an owner of the account must approve it on GitHub first), declined , other_org , needs_admin , not_installer , wrong_user , expired or failed , with a sentence that says what happened and what to do next.](https://www.promigence.ai/docs/reference/api/github#get-v1-integrations-github-requests-request-id)
- [DELETE /v1/integrations/github/tracks/{track_id} Stop a snapshot following its branch.](https://www.promigence.ai/docs/reference/api/github#delete-v1-integrations-github-tracks-track-id)

## GitLab

[All 7 in full](https://www.promigence.ai/docs/reference/api/gitlab)

- [GET /v1/integrations/gitlab Your organization's GitLab connections (each with the URL and token of an optional project webhook that makes tracked branches build at once), the ones waiting for an owner to confirm, and the snapshots that follow a branch.](https://www.promigence.ai/docs/reference/api/gitlab#get-v1-integrations-gitlab)
- [POST /v1/integrations/gitlab/connect Start connecting a GitLab user: a link to authorize the platform's GitLab application, read-only ( read_api read_repository ), valid for 15 minutes.](https://www.promigence.ai/docs/reference/api/gitlab#post-v1-integrations-gitlab-connect)
- [DELETE /v1/integrations/gitlab/connections/{connection_id} Disconnect a GitLab user: the authorization is revoked on GitLab, nothing is built from it any more and the snapshots that followed branches through it stop following them.](https://www.promigence.ai/docs/reference/api/gitlab#delete-v1-integrations-gitlab-connections-connection-id)
- [GET /v1/integrations/gitlab/repos The projects a GitLab connection can read (the oldest working one unless connection_id names another), one page at a time ( page , per_page up to 100).](https://www.promigence.ai/docs/reference/api/gitlab#get-v1-integrations-gitlab-repos)
- [POST /v1/integrations/gitlab/requests Start connecting a GitLab user in the console, for yourself: a one-time ticket (5 minutes) and the console page that uses it ( connect_url ).](https://www.promigence.ai/docs/reference/api/gitlab#post-v1-integrations-gitlab-requests)
- [GET /v1/integrations/gitlab/requests/{request_id} How a GitLab connection request you started ended: pending , then connected , already_connected , declined , wrong_user , expired or failed , with a sentence that says what happened and what to do next.](https://www.promigence.ai/docs/reference/api/gitlab#get-v1-integrations-gitlab-requests-request-id)
- [DELETE /v1/integrations/gitlab/tracks/{track_id} Stop a snapshot following its GitLab branch.](https://www.promigence.ai/docs/reference/api/gitlab#delete-v1-integrations-gitlab-tracks-track-id)

## Runs

[All 12 in full](https://www.promigence.ai/docs/reference/api/runs)

- [DELETE /v1/captures/{id} Destroy a preserved failure now.](https://www.promigence.ai/docs/reference/api/runs#delete-v1-captures-id)
- [GET /v1/runs List your org's runs, newest first.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs)
- [POST /v1/runs Fork N sandboxes from one snapshot, optionally running a command in each.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs)
- [GET /v1/runs/{id} One run and its sandboxes.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs-id)
- [DELETE /v1/runs/{id} Cancel the queue and kill every live sandbox of the run.](https://www.promigence.ai/docs/reference/api/runs#delete-v1-runs-id)
- [POST /v1/runs/{id}/cancel Stop what is still queued.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs-id-cancel)
- [GET /v1/runs/{id}/captures What is preserved of this run's failures, and when each goes.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs-id-captures)
- [POST /v1/runs/{id}/open Reopen a preserved failure as a new, live sandbox — the state the sandbox was in when it broke, not a re-run from the start.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs-id-open)
- [POST /v1/runs/{id}/replay Re-fork the sandboxes whose outcome was an environment failure.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs-id-replay)
- [GET /v1/runs/{id}/report The validity report: every sandbox, its outcome, and whether the failure was the environment's or the task's.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs-id-report)
- [GET /v1/runs/{id}/sandboxes Only the sandboxes of a run.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs-id-sandboxes)
- [POST /v1/runs/quote Price a run without starting one.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs-quote)

## Sandboxes

[All 10 in full](https://www.promigence.ai/docs/reference/api/sandboxes)

- [GET /v1/sandboxes List your org's sandboxes, newest first.](https://www.promigence.ai/docs/reference/api/sandboxes#get-v1-sandboxes)
- [GET /v1/sandboxes/{id} One sandbox, with its execs.](https://www.promigence.ai/docs/reference/api/sandboxes#get-v1-sandboxes-id)
- [PATCH /v1/sandboxes/{id} Extend a live sandbox's total lifetime, and set when it parks itself.](https://www.promigence.ai/docs/reference/api/sandboxes#patch-v1-sandboxes-id)
- [DELETE /v1/sandboxes/{id} Kill it now. The answer's outcome says how it ended: aborted_by_client for a sandbox that had started, billed for the seconds it used; not_started for one still queued, which is not billed; or, when its command had already returned, that command's own outcome.](https://www.promigence.ai/docs/reference/api/sandboxes#delete-v1-sandboxes-id)
- [GET /v1/sandboxes/{id}/network Read the network policy a live sandbox is running under.](https://www.promigence.ai/docs/reference/api/sandboxes#get-v1-sandboxes-id-network)
- [POST /v1/sandboxes/{id}/network Cut a live sandbox's egress.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-network)
- [POST /v1/sandboxes/{id}/pause Park the sandbox: it does not count against your concurrency limit, and paused time is not billed.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-pause)
- [POST /v1/sandboxes/{id}/probe Re-check the sandbox's files against what the verified snapshot recorded.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-probe)
- [POST /v1/sandboxes/{id}/resume Bring a paused sandbox back where it was, and restart the billing clock.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-resume)
- [POST /v1/sandboxes/{id}/snapshot Snapshot a running sandbox without stopping it, and get back an ordinary snapshot id you can fork.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-snapshot)

## Execs

[All 7 in full](https://www.promigence.ai/docs/reference/api/execs)

- [GET /v1/execs/{id} One exec by id alone, without knowing its sandbox or run.](https://www.promigence.ai/docs/reference/api/execs#get-v1-execs-id)
- [GET /v1/sandboxes/{id}/execs List this sandbox's background execs.](https://www.promigence.ai/docs/reference/api/execs#get-v1-sandboxes-id-execs)
- [POST /v1/sandboxes/{id}/execs Run a command. Buffered by default; Accept: text/event-stream streams it; background: true returns 202 with a handle instead of waiting.](https://www.promigence.ai/docs/reference/api/execs#post-v1-sandboxes-id-execs)
- [GET /v1/sandboxes/{id}/execs/{exec_id} Read a background exec.](https://www.promigence.ai/docs/reference/api/execs#get-v1-sandboxes-id-execs-exec-id)
- [DELETE /v1/sandboxes/{id}/execs/{exec_id} SIGKILL the background exec and drop its handle and buffered output.](https://www.promigence.ai/docs/reference/api/execs#delete-v1-sandboxes-id-execs-exec-id)
- [POST /v1/sandboxes/{id}/execs/{exec_id}/signal Signal a background exec.](https://www.promigence.ai/docs/reference/api/execs#post-v1-sandboxes-id-execs-exec-id-signal)
- [POST /v1/sandboxes/{id}/execs/{exec_id}/stdin Write to a running command's standard input, and close it.](https://www.promigence.ai/docs/reference/api/execs#post-v1-sandboxes-id-execs-exec-id-stdin)

## Files

[All 12 in full](https://www.promigence.ai/docs/reference/api/files)

- [GET /v1/sandboxes/{id}/files Stream a file out. ?path= .](https://www.promigence.ai/docs/reference/api/files#get-v1-sandboxes-id-files)
- [PUT /v1/sandboxes/{id}/files Write a file in. ?path= ; the body is the bytes.](https://www.promigence.ai/docs/reference/api/files#put-v1-sandboxes-id-files)
- [DELETE /v1/sandboxes/{id}/files Delete a path. Idempotent: a missing path answers existed: false , not 404.](https://www.promigence.ai/docs/reference/api/files#delete-v1-sandboxes-id-files)
- [POST /v1/sandboxes/{id}/files/archive Pack a directory into a tar **inside the sandbox** and answer with where it landed and how big it is.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-archive)
- [POST /v1/sandboxes/{id}/files/chmod Change permissions and ownership.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-chmod)
- [POST /v1/sandboxes/{id}/files/copy Copy a file, or a whole tree with recursive .](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-copy)
- [POST /v1/sandboxes/{id}/files/extract Unpack a tar that is already inside the sandbox.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-extract)
- [GET /v1/sandboxes/{id}/files/list List a directory. ?path= , plus ?recursive=1 , ?depth=N , ?limit=N and ?hidden=0 .](https://www.promigence.ai/docs/reference/api/files#get-v1-sandboxes-id-files-list)
- [POST /v1/sandboxes/{id}/files/mkdir Create a directory. parents is mkdir -p and makes an existing directory a success; without it a missing parent is a 404 and an existing path is a conflict, which is what a caller using the call as a lock wants.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-mkdir)
- [POST /v1/sandboxes/{id}/files/move Rename or move a path.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-move)
- [GET /v1/sandboxes/{id}/files/search Find files under ?path= .](https://www.promigence.ai/docs/reference/api/files#get-v1-sandboxes-id-files-search)
- [GET /v1/sandboxes/{id}/files/stat Size, mode, mtime and kind for one path.](https://www.promigence.ai/docs/reference/api/files#get-v1-sandboxes-id-files-stat)

## Ports and terminal

[All 8 in full](https://www.promigence.ai/docs/reference/api/ports-and-terminal)

- [GET /v1/sandboxes/{id}/ports List this sandbox's preview URLs.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#get-v1-sandboxes-id-ports)
- [POST /v1/sandboxes/{id}/ports Mint a preview URL for a port in the sandbox.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#post-v1-sandboxes-id-ports)
- [DELETE /v1/sandboxes/{id}/ports/{token_or_port} Revoke one URL by its token, or every URL for a port by the port number.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#delete-v1-sandboxes-id-ports-token-or-port)
- [GET /v1/sandboxes/{id}/pty A WebSocket terminal, relayed byte for byte.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#get-v1-sandboxes-id-pty)
- [GET /v1/sandboxes/{id}/ssh The keys this sandbox will accept over SSH, and for how long.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#get-v1-sandboxes-id-ssh)
- [POST /v1/sandboxes/{id}/ssh Authorise an ssh-ed25519 public key for this sandbox and mint the short-lived credential an SSH connection to it uses.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#post-v1-sandboxes-id-ssh)
- [DELETE /v1/sandboxes/{id}/ssh/{key_id} Revoke one key by id or fingerprint, and the access credential issued with it.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#delete-v1-sandboxes-id-ssh-key-id)
- [GET /v1/sandboxes/{id}/ssh/connect A WebSocket carrying the SSH byte stream, relayed byte for byte.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#get-v1-sandboxes-id-ssh-connect)

## Secrets

[All 3 in full](https://www.promigence.ai/docs/reference/api/secrets)

- [GET /v1/secrets The calling key's project's secret names and shapes, and for a bound secret its urls and env as POST /v1/secrets answers them.](https://www.promigence.ai/docs/reference/api/secrets#get-v1-secrets)
- [POST /v1/secrets Store a secret in the calling key's project (the same name may hold a different value in another project).](https://www.promigence.ai/docs/reference/api/secrets#post-v1-secrets)
- [DELETE /v1/secrets/{name} Remove a secret.](https://www.promigence.ai/docs/reference/api/secrets#delete-v1-secrets-name)

## Organisation

[All 24 in full](https://www.promigence.ai/docs/reference/api/organisation)

- [GET /v1/invites Invites waiting for your verified email address, from any organization.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-invites)
- [POST /v1/invites/{invite_id}/accept Accept an invite and join the organization.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-invites-invite-id-accept)
- [POST /v1/invites/{invite_id}/decline Decline an invite sent to your verified email address.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-invites-invite-id-decline)
- [GET /v1/me Who you are, what your limits are, what you have spent, and what trial credit is left.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-me)
- [GET /v1/me/ledger The rows behind spend: usage recorded while each sandbox runs and when it ends.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-me-ledger)
- [GET /v1/me/outcomes 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.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-me-outcomes)
- [GET /v1/orgs The organizations you belong to, your role in each, and which one is your default.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs)
- [POST /v1/orgs Create an organization.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs)
- [PATCH /v1/orgs/{org} Rename an organization.](https://www.promigence.ai/docs/reference/api/organisation#patch-v1-orgs-org)
- [DELETE /v1/orgs/{org} Delete an organization.](https://www.promigence.ai/docs/reference/api/organisation#delete-v1-orgs-org)
- [GET /v1/orgs/{org}/audit 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 ).](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs-org-audit)
- [POST /v1/orgs/{org}/default Make this organization the one a sign-in and the CLI use when none is named.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-default)
- [GET /v1/orgs/{org}/invites Pending invites to an organization.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs-org-invites)
- [POST /v1/orgs/{org}/invites Invite an email address.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-invites)
- [DELETE /v1/orgs/{org}/invites/{invite_id} Revoke a pending invite.](https://www.promigence.ai/docs/reference/api/organisation#delete-v1-orgs-org-invites-invite-id)
- [POST /v1/orgs/{org}/invites/{invite_id}/resend Send a pending invite's email again: the same invite, its 14 days counted again from now.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-invites-invite-id-resend)
- [GET /v1/orgs/{org}/members The members of an organization and their roles.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs-org-members)
- [PATCH /v1/orgs/{org}/members/{user_id} Change a member's role.](https://www.promigence.ai/docs/reference/api/organisation#patch-v1-orgs-org-members-user-id)
- [DELETE /v1/orgs/{org}/members/{user_id} Remove a member (owners, signed in), or leave (your own user id, or me ).](https://www.promigence.ai/docs/reference/api/organisation#delete-v1-orgs-org-members-user-id)
- [GET /v1/orgs/{org}/projects 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.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs-org-projects)
- [POST /v1/orgs/{org}/projects Create a project.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-projects)
- [PATCH /v1/orgs/{org}/projects/{project} Rename a project, set its monthly cap, or both.](https://www.promigence.ai/docs/reference/api/organisation#patch-v1-orgs-org-projects-project)
- [DELETE /v1/orgs/{org}/projects/{project} Delete a project with no working keys, no snapshots, no builds running, no failure captures and no sandbox that has not ended.](https://www.promigence.ai/docs/reference/api/organisation#delete-v1-orgs-org-projects-project)
- [POST /v1/orgs/{org}/projects/{project}/move 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).](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-projects-project-move)

## Billing

[All 10 in full](https://www.promigence.ai/docs/reference/api/billing)

- [GET /v1/billing Plan, card on file, this month's usage, and the upcoming invoice preview.](https://www.promigence.ai/docs/reference/api/billing#get-v1-billing)
- [POST /v1/billing/checkout Start a card-setup checkout.](https://www.promigence.ai/docs/reference/api/billing#post-v1-billing-checkout)
- [GET /v1/billing/history Your billing history, newest first: every credit you received, with what is left of it and when it expires, and every payment (invoices paid, payments that failed, refunds).](https://www.promigence.ai/docs/reference/api/billing#get-v1-billing-history)
- [POST /v1/billing/portal A link to the billing portal.](https://www.promigence.ai/docs/reference/api/billing#post-v1-billing-portal)
- [POST /v1/credits/claim The claim the page sends: the link's token, the accepted terms version and the page's browser check.](https://www.promigence.ai/docs/reference/api/billing#post-v1-credits-claim)
- [POST /v1/credits/claim-link A single-use link (15 minutes) to the page where the free credit is claimed ( promigence credits claim opens it).](https://www.promigence.ai/docs/reference/api/billing#post-v1-credits-claim-link)
- [GET /v1/credits/offer Your account's free credit: claimable (and how much, until when), claimed, being checked, needs a card, or none.](https://www.promigence.ai/docs/reference/api/billing#get-v1-credits-offer)
- [GET /v1/pricing Your organization's price list, read live on every call from what billing charges: the per-second rates, every sandbox shape on sale and its price (a snapshot build is billed at its tier's), the limits, the free credit and the plan they come from ( scope: organization ).](https://www.promigence.ai/docs/reference/api/billing#get-v1-pricing)
- [GET /v1/referrals Your referral code and its offer ("Give $X, get $Y"), your referrals by status, what they earned you, the referral you came through, and your credit that expires.](https://www.promigence.ai/docs/reference/api/billing#get-v1-referrals)
- [POST /v1/referrals/apply Apply a referral code to your organization: before its first paid invoice and within the offer's window after the organization was created.](https://www.promigence.ai/docs/reference/api/billing#post-v1-referrals-apply)

## Keys and sign-in

[All 12 in full](https://www.promigence.ai/docs/reference/api/keys-and-sign-in)

- [GET /v1/auth/claim The page where the free credit is claimed, in a browser: the offer, the terms to accept, and the Claim button.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#get-v1-auth-claim)
- [GET /v1/auth/cli-callback The page a browser lands on after sign-in; in headless mode it shows the code to paste back.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#get-v1-auth-cli-callback)
- [POST /v1/auth/cli/requests Start promigence login through the console: register the sign-in request (the PKCE S256 challenge, the state, the local port the CLI listens on or none to paste the code, the computer's name and the new key's name) and get the authorize page to open for it.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-cli-requests)
- [POST /v1/auth/cli/token Finish promigence login after you authorized the CLI in the browser: exchange the one-time code the authorize page gave the CLI, with the PKCE verifier whose S256 challenge the CLI sent there, for an API key ( api_key , in this answer only).](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-cli-token)
- [GET /v1/auth/config What promigence login needs to start a sign-in: the identity domain, client id and scopes, and the console page where you authorize the CLI ( console_authorize_url , when it is offered).](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#get-v1-auth-config)
- [POST /v1/auth/invite Redeem an invite code for one sign-in attempt, before the sign-in starts ( promigence signup does it for you).](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-invite)
- [POST /v1/auth/invite/release Give back the place a redeemed invite code holds for a sign-in attempt that ended without an account (it timed out or was cancelled), so the next attempt can redeem the code at once ( promigence signup does it for you).](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-invite-release)
- [POST /v1/auth/session Exchange an identity token for a Promigence API key.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-session)
- [GET /v1/keys List your org's keys: with an API key, its own project's; with an identity token, every project's.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#get-v1-keys)
- [POST /v1/keys Mint a key. api_key is in the 201 response and is never retrievable again.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-keys)
- [DELETE /v1/keys/{key_id} Revoke a key, and every key it minted (and every key those minted): also_revoked lists them.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#delete-v1-keys-key-id)
- [POST /v1/orgs/{org}/keys Mint a key in an organization you belong to, in one of its projects.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-orgs-org-keys)

[The same operations from the CLI](https://www.promigence.ai/docs/cli) · [from TypeScript](https://www.promigence.ai/docs/sdk) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors)