API
Every endpoint of the Parity API, with the permission each one needs.
All requests go to https://api.parity.ninja with a bearer token. Responses are JSON. Errors are RFC 9457 problem details; see Errors.
curl -H "Authorization: Bearer $PARITY_TOKEN" https://api.parity.ninja/v0/sandboxesThe CLI and the MCP server call these endpoints and return the same JSON. Every endpoint names one permission; the role table is in Permissions.
Token
Describe the token
Projects
List projects
Create a project
Check a project name
Get a project
Path: project.
Check a manifest against the project
Path: project.
Create a project token
Path: project.
Promote a manifest
Path: project.
environment_list
Path: project.
Environment status
Read a project's environments (staging, production, customer deployments: whatever its manifest declares): whether each is frozen or pinned by a rollback, its current rollout and status, and the block jobs waiting for a person with their prompts. With environment, that one in full. Builds move between environments through releases: see release_status. Agents can't promote, approve or reject: tell the user what is waiting and that they decide it (parity approve <step> --env <environment>, or the console).
Path: project, environment. Arguments and behaviour match the MCP tool environment_status.
environment_retry
Path: project, environment.
environment_rollback
Path: project, environment.
environment_delete
Path: project, environment.
environment_promote
Path: project, environment.
step_approve
Path: project, environment, step.
step_reject
Path: project, environment, step.
release_list
Path: project.
Release status
Read a project's releases, newest first: each is one build moving through the manifest's release steps (promote into environments, block for approval, wait, run a job, group). Shows where each release is and what it waits for: a block's prompt and approvals, a promote's environments (held: frozen or pinned by a rollback), a wait's end. With number, that release in full. Agents can't approve, reject or skip: tell the user what waits and that they decide it (parity approve <step>, or the console).
Path: project, release. Arguments and behaviour match the MCP tool release_status.
release_step_approve
Path: project, release, step.
release_step_reject
Path: project, release, step.
release_step_skip
Path: project, release, step.
Freeze an environment
Path: project, environment.
Lift a freeze
Path: project, environment.
List build runners
Path: project.
GitHub
List GitHub App installations
Start a GitHub App installation
Finish a GitHub App installation
List an installation's repositories
Path: installation.
Read a repository's parity.yaml
Path: repo.
Sandboxes
List sandboxes
List the sandboxes this token can see, with status and expiry, a page at a time: while next_page_token is set, call again with it as page_token.
Arguments and behaviour match the MCP tool sandbox_list.
Render a sandbox's objects
Upload source
Create a sandbox
Create a sandbox for one task: the app's services, database, mail and auth in their own namespace. Needs a project token. The sandbox's createdBy is the person the token was minted for. Returns the sandbox (id, status, domain, services[].public_urls) and its token at once: give that sandbox token to the agent doing the task. With wait (the default) it then waits up to about 50 seconds for ready, sending progress; if the sandbox is still starting it returns with next: call sandbox_status with wait until status is ready. A failed setup job is dependency_failed with the log tail. Pass idempotency_key to make a retry return the same sandbox and token.
Arguments and behaviour match the MCP tool sandbox_create.
Sandbox status
Get a sandbox: status (starting, ready, failed, expiring), expires_at, services with public_urls and health, resources, lifecycle jobs and conditions. With wait, it waits up to about 50 seconds for ready (or failed), sending progress; call it again while status is starting. The app's URL is services[].public_urls.
Path: id. Arguments and behaviour match the MCP tool sandbox_status.
Destroy the sandbox
Destroy the sandbox and all its data. Its token stops working. Exported proofs and calls.jsonl are kept by Parity (GET /v0/proofs), but export the proof first: nothing can be exported after.
Path: id. Arguments and behaviour match the MCP tool sandbox_destroy.
Roll onto a changed manifest or new images
Roll the sandbox onto a changed parity.yaml (manifest: its text), new prebuilt images (images: {service: ref}), or both; deploy jobs such as migrations run again. Waits up to about 50 seconds for ready unless wait is false. To run changed source code, use parity up from the working directory: it uploads the tree and Parity rebuilds the services that only have build:.
Path: id. Arguments and behaviour match the MCP tool sandbox_sync.
Extend the lifetime
Push the sandbox's expiry back by a duration, such as 1h, up to the manifest's max_ttl. Returns the sandbox with the new expires_at.
Path: id. Arguments and behaviour match the MCP tool sandbox_extend.
Scale a service
Path: id, service.
Run a command in a service
Run a command in a running service or resource container (such as psql in db, or a script in web) and return {exit_code, stdout, stderr}. Output is capped at 1 MiB per stream. The sandbox's generated values are replaced with [redacted] where they appear verbatim, as a courtesy: exec can read the env, so treat its output as secret-bearing.
Path: id. Arguments and behaviour match the MCP tool sandbox_exec.
Read logs
Read logs as text: one service, resource or job, or the whole sandbox when neither is given. Several containers are prefixed with [pod/container]. Use since to see only what an action just caused.
Path: id. Arguments and behaviour match the MCP tool sandbox_logs.
Egress report
Every outbound call the sandbox made: DNS queries for outside names and connections to outside hosts (HTTP Host, TLS server name), blocked or let through, with the service that tried and a count. A blocked host needs adding to the manifest's externals. sandbox_status lists the blocked hosts too.
Path: id. Arguments and behaviour match the MCP tool sandbox_egress.
Auth users
Auth users and sign-in links
Path: id, rest.
Inbox
List the inbox
List the mail the sandbox received (every address at the sandbox's domains lands here), newest first: id, to, from, subject, received_at, snippet, and the links, codes and attachments extracted from each. Filter by recipient, subject text or regexp, since, or after (a cursor); q searches every message, not just one page. The answer's cursor is the newest message: pass it as inbox_wait's after to get the next mail once you have acted. inbox_read gives one message's text. While next_page_token is set, older mail is on the next page (page_token).
Path: id. Arguments and behaviour match the MCP tool inbox_list.
Wait for a message
Wait for a message (to an address, with subject text or a subject regexp) and return it with its text, links, codes and attachments. Without after, it returns the newest match, even one that came before the call, so call it right after the action that sends mail. With after (a message id, or the cursor inbox_list gave before you acted), it returns the first match after that message, so old mail never answers. expect_none asserts that no match arrives in the window instead (signed evidence that something was not sent). Waits at most 50 seconds, sending progress; on timeout call again with the after the answer gives. Prefer links with internal: true.
Path: id. Arguments and behaviour match the MCP tool inbox_wait.
Read a message
Read one message: its text, the extracted links and codes (one-time codes, verification links) and its attachments (part, name, content_type, size; inbox_attachment downloads one). The HTML part only with html: true.
Path: id, msg. Arguments and behaviour match the MCP tool inbox_read.
Download a mail attachment
Download one attachment of a message, by its part or file name (inbox_read lists them), as an embedded resource with its content type; with parity mcp, save_to writes it to a local file. Without part, lists the attachments.
Path: id, msg, part. Arguments and behaviour match the MCP tool inbox_attachment.
Jobs
Run a job
Run one of the manifest's jobs now (a seed, a migration, a cron's task), from the app version the sandbox runs. Waits up to about 50 seconds, sending progress, and returns {job, name, status, log_tail, duration_seconds}; a failure is dependency_failed with the log tail. A job still running returns status running with next: call job_status with its name.
Path: id, job. Arguments and behaviour match the MCP tool job_run.
Job run status
The state of one job run (from job_run's name), waiting up to about 50 seconds for it to finish, with progress.
Path: id, job, run. Arguments and behaviour match the MCP tool job_status.
Proof and records
List proof files
Path: id.
Attach to the proof
Attach evidence to the sandbox's proof bundle: a screenshot, a test log, an API response. It lands in files/ of the export, with your note and its content type. Give text as content, bytes as content_base64 (or, with parity mcp, a local path); several files at once in files. Returns {name, size, sha256, content_type}, or {files: [...]} for several.
Path: id. Arguments and behaviour match the MCP tool proof_add.
Export the proof
Export the proof bundle as a zip: proof.json (sandbox, commit, image digests, times, users created, your verdict), calls.jsonl (every API call this token made), inbox/.eml, egress.json, logs/.log and files/*. Fill claim, result and summary for the reviewer. Returns the list of entries and the zip as an embedded resource (or writes it to save_to with parity mcp).
Path: id. Arguments and behaviour match the MCP tool proof_export.
Download a proof bundle
Path: id, proof.
List proofs
Get a proof
Path: proof.
List records
Read a record's calls
Path: record.
Public keys
The ed25519 public keys Parity signs proof bundles with, as { "keys": [...] }. parity proof verify checks bundles against them.