REST API - Pome

Description

The Pome REST API is the control plane at https://api.pome.sh/v1. It starts sandboxes, seeds them with a world of your own, and hands back the evidence a run produced. Everything the CLI and the MCP server do, they do by calling it. Reach for it directly when you are bringing your own evaluation harness. Pome gives you a deterministic world and a recorded tape; your harness decides what counts as a pass. If you would rather have Pome grade the run too, that works over the same API — see finalize. Every response is JSON except the markdown run report, which is text/markdown.

Base URL and versioning

https://api.pome.sh/v1

v1 is the only version. Responses are tolerant-reader by design: the control plane may add fields to a response, so parse the keys you need and ignore the rest rather than rejecting an unfamiliar body. Two other hosts appear in responses, and neither is this API:

Host	What it serves
`twins.pome.sh`	The digital twins themselves. A sandbox’s `per_twin[].api_url` and `.mcp_url` point here. Your agent talks to this host, with the sandbox’s `agent_token`.
`app.pome.sh`	The dashboard. `dashboard_url` in a finalize response links here.

Authentication

Every endpoint takes a team API key as a bearer token:

curl https://api.pome.sh/v1/me \
  -H "Authorization: Bearer $POME_API_KEY"

Keys are shaped pme_<id>_<secret> and are minted in the dashboard, or by pome login, which stores one where the CLI can find it. The key is team-scoped: every sandbox, run, and task it can see belongs to that team.

A sandbox’s agent_token is not an API key. It is a short-lived bearer, scoped to one sandbox and expiring with it, and it authenticates calls to the twins on twins.pome.sh — never to api.pome.sh/v1. Hand that one to your agent; keep the pme_ key out of the agent’s environment.

Two failures are deliberately distinguishable:

Code	Type	Meaning
`401`	`invalid_auth`	Malformed key, unknown id, or wrong secret. All three collapse into one answer so the API never reveals whether an id exists.
`403`	`revoked_key`	The key was valid and has been revoked. Distinct on purpose — “wrong key” and “your key was turned off” need different fixes.

How errors arrive

Every error is the same envelope. Sibling pages link back to this table rather than repeating it.

{
  "error": {
    "type": "validation_failed",
    "message": "Seed is not valid for the github twin: repositories[0].name — Invalid input: expected string, received undefined",
    "details": {
      "error": "invalid_seed",
      "twin": "github",
      "issue_count": 1,
      "issues": [
        {
          "path": "repositories[0].name",
          "message": "Invalid input: expected string, received undefined",
          "code": "invalid_type"
        }
      ]
    },
    "request_id": "req_H0iS10S1UhAB"
  }
}

type is the coarse class and is drawn from a closed set. details is where the specific failure lives — branch on details.error when you need to tell two validation_faileds apart. request_id is on every error; quote it if you ask us about one.

Code	`type`	What to do
`400`	`validation_failed`	The body was not JSON at all. Some endpoints answer `422` for the same thing — treat the two as one case rather than branching on the code.
`401`	`invalid_auth`	Check the key.
`402`	`quota_exceeded`	Too many sandboxes open at once. Stop one, or raise the plan. `details.usage` names the numbers.
`403`	`revoked_key`	The key was revoked.
`404`	`not_found`	No such id, or it belongs to another team. The two are never distinguished.
`409`	`conflict`	The request collided with the resource’s state — an ungraded sandbox you asked to delete, or a capture that could not complete. `details.reason` says which.
`410`	`session_expired`	The sandbox is closed. Nothing is recoverable; start a new one.
`413`	`validation_failed`	The body is over the cap. See Limits.
`422`	`validation_failed`	A field is wrong, and the message names it.
`500`	`internal_error`	Ours. Retry once, then quote the `request_id`.
`503`	`downstream_unavailable`	Something we depend on could not answer — a sandbox that would not provision, or evidence storage we could not reach. Retry.

Quota trips are 402, never 429. A 402 will not clear on its own — free a sandbox or raise the plan.

The error vocabulary worth branching on

These are the named failures a caller hits in normal use. Most arrive as 422 under details.error. The last three carry a different code and live under details.reason instead — each row says which key and which code.

`details` key	Raised by	Meaning
`invalid_seed`	seed validate, sandbox create	A twin’s own parser refused the world. Carries `twin`, `issue_count`, and up to 25 `issues[]`, each with a `path`.
`invalid_seed_envelope`	seed validate, sandbox create	A multi-twin seed was not a per-twin envelope, or named a twin the sandbox does not have. Stray names come back in `stray_twins`.
`malformed_scenario_seed`	sandbox create	The seed block inside a `task_source` markdown could not be parsed.
`unknown_twins`	seed validate, sandbox create	A twin id that is not mounted. `available` lists the real ones.
`too_many_twins`	sandbox create	More than three twins in one sandbox.
`twin_snapshot_unavailable`	sandbox create	A mounted twin has no image configured in this deploy. Ours, not yours.
`empty_criteria`	finalize	Zero criteria. A run with nothing to check is never graded.
`ungraded_session`	sandbox delete	`409`, under `details.reason`. You asked to delete a sandbox whose run has not been graded. Carries a `discard_token` to confirm with.
`capture_incomplete`	finalize	`409`, under `details.reason`. The tape could not be read.
`blob_absent`	run trace / state download	`404`, under `details.reason`. The run is yours, but that blob was never stored — self-host, `--no-upload`, or a row older than the upload path.

Endpoint index

Every endpoint is documented on the endpoints page with the same shape: what it does, an input table, what comes back, the errors worth branching on, and one example call.

Identity and quota

Endpoint	What it does
`GET /v1/me`	Who the key belongs to. The cheapest way to check a key works.
`GET /v1/usage`	How many sandboxes you have open, and how many you may.

Seeds

Endpoint	What it does
`POST /v1/seeds/validate`	Would this world boot, and if not, which field? No sandbox, no quota, no charge.

Sandboxes

Endpoint	What it does
`POST /v1/sandboxes`	Start a sandbox with one to three digital twins, optionally seeded with your own world.
`GET /v1/sandboxes`	List your sandboxes, newest first.
`GET /v1/sandboxes/:id`	One sandbox, including its `agent_token`.
`POST /v1/sandboxes/:id/heartbeat`	Reset the idle timer on a sandbox you are still using.
`DELETE /v1/sandboxes/:id`	Stop a sandbox. Refused on an ungraded run unless you confirm.

Grading vocabulary

Endpoint	What it does
`GET /v1/checks`	The closed set of `[code]` checks a twin can grade.
`POST /v1/checks/render`	Turn a picked check plus arguments into the exact sentence the grader binds.
`POST /v1/checks/bind`	The inverse: does this sentence bind, and to what?

Runs and evidence

Endpoint	What it does
`POST /v1/sandboxes/:id/finalize`	Grade the run and close the sandbox.
`GET /v1/sandboxes/:id/evaluation`	Poll an asynchronous finalize.
`GET /v1/runs`	List runs, newest first.
`GET /v1/runs/:id`	One run: score, every per-criterion verdict, and its reason.
`GET /v1/runs/:id/report.md`	The same run as a rendered markdown report.
`GET /v1/runs/:id/trace`	A signed, short-lived download URL for the run’s raw tape.
`GET /v1/runs/:id/state`	The same, for the twin’s final state.

The loop, end to end

Four calls take you from nothing to a running agent in a world you wrote. Each one links to its full entry.

export POME_API_KEY=pme_...

# 1. Does the world you wrote parse? Free, and no sandbox is started.
curl -sX POST https://api.pome.sh/v1/seeds/validate \
  -H "Authorization: Bearer $POME_API_KEY" -H 'Content-Type: application/json' \
  -d '{"twins":["github"],"seed":{
        "users":[{"login":"northwind","type":"Organization"}],
        "repositories":[{"owner":"northwind","name":"payments","default_branch":"main",
          "issues":[{"number":1,"title":"Refunds fail on partial capture","state":"open"}]}]}}'
# {"valid":true,"checked":["github"],"unchecked":[]}

# 2. Start a sandbox on that world.
curl -sX POST https://api.pome.sh/v1/sandboxes \
  -H "Authorization: Bearer $POME_API_KEY" -H 'Content-Type: application/json' \
  -d '{"twins":["github"],"task_source":"IyAuLgo=","seed":{ ... }}' > sandbox.json

# 3. Point your agent at the twin and let it work. Two values are all it needs.
export POME_GITHUB_REST_URL=$(jq -r .per_twin.github.api_url sandbox.json)
export POME_AUTH_TOKEN=$(jq -r .agent_token sandbox.json)

# 4. Read what your agent actually did, straight off the twin.
curl -s "$POME_GITHUB_REST_URL/_pome/events" -H "Authorization: Bearer $POME_AUTH_TOKEN"

Step 4 is the tape: one row per HTTP call the agent made, with method, path, request body, and what the twin answered. It is live for as long as the sandbox is, it costs nothing, and it is what a bring-your-own-eval harness scores against. The digital twin quickstarts work through reading it.

task_source in step 2 is IyAuLgo= — base64 for # .., a stub. Today POST /v1/sandboxes requires a task even when you have brought a seed and will never read one. The full entry explains why, and it is the one wart on this path.

To have Pome grade the run instead of scoring it yourself, add a fifth call — finalize — while the sandbox is still live.

Limits

Limit	Value	What happens past it
Twins per sandbox	3	`422` `too_many_twins`.
Sandbox lifetime	30 minutes	The sandbox expires. Finalize before then, or the run cannot be scored.
Idle timeout	30 minutes	Reset by any call through the twin, or by an explicit heartbeat.
`POST /v1/sandboxes` body	4 MiB	`413`.
`POST /v1/seeds/validate` body	4 MiB	`413`.
Finalize body	256 KiB	`413`. Blobs never travel in this body.
Criteria per finalize	200	`422`.
Seed issues reported	25	Truncated; `issue_count` always carries the true total.

Concurrent sandboxes are a plan limit rather than a fixed number — GET /v1/usage reports yours.

​Description

​Base URL and versioning

​Authentication

​How errors arrive

​The error vocabulary worth branching on

​Endpoint index

​Identity and quota

​Seeds

​Sandboxes

​Grading vocabulary

​Runs and evidence

​The loop, end to end

​Limits

​See also

Description

Base URL and versioning

Authentication

How errors arrive

The error vocabulary worth branching on

Endpoint index

Identity and quota

Seeds

Sandboxes

Grading vocabulary

Runs and evidence

The loop, end to end

Limits

See also