putty
API ReferenceOperator

Read the operator overview

A single read-only snapshot of the platform: dependency health, the run queue's depth, every active run with the age of its lease, and the buyback amount owed. `buyback.owedUsd` is a decimal string summing `RevenueEntry.buybackShareUsd` over the whole ledger, which is the spec's record of the share every payment marks (`prompt.md:1610-1612`). Execution of a buyback is manual and timing-discretionary per `tokenomics.md`; this route only reports the obligation. It is a string rather than a number because the column is `TEXT` and dollar amounts are never summed as floats. **Authorization.** Send the operator token as a bearer: `Authorization: Bearer $OPERATOR_TOKEN`. A request with no token is `401`; a token that is not the operator token is `403`. When `OPERATOR_TOKEN` is unset the route refuses every caller, including one holding a valid Privy session — it denies by default rather than falling back to a permissive check.

GET
/operator

A single read-only snapshot of the platform: dependency health, the run queue's depth, every active run with the age of its lease, and the buyback amount owed. buyback.owedUsd is a decimal string summing RevenueEntry.buybackShareUsd over the whole ledger, which is the spec's record of the share every payment marks (prompt.md:1610-1612). Execution of a buyback is manual and timing-discretionary per tokenomics.md; this route only reports the obligation. It is a string rather than a number because the column is TEXT and dollar amounts are never summed as floats. Authorization. Send the operator token as a bearer: Authorization: Bearer $OPERATOR_TOKEN. A request with no token is 401; a token that is not the operator token is 403. When OPERATOR_TOKEN is unset the route refuses every caller, including one holding a valid Privy session — it denies by default rather than falling back to a permissive check.

Authorization

bearerAuth
AuthorizationBearer <token>

A bearer token. The Account routes accept a Privy access token; the MCP transport accepts an sk- API key issued by POST /account/api-keys.

In: header

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/operator"
{  "generatedAt": "string",  "health": {    "database": {      "status": "up",      "detail": "string"    },    "queue": {      "status": "up",      "detail": "string"    },    "sandbox": {      "status": "up",      "detail": "string"    }  },  "queue": {    "pending": 0,    "total": 0,    "workers": 0  },  "activeRuns": [    {      "id": "string",      "projectId": "string",      "status": "queued",      "model": "string",      "steps": 0,      "startedAt": "string",      "heartbeatAgeMs": 0,      "stale": true    }  ],  "buyback": {    "owedUsd": "string",    "entries": 0  }}

Read the product metrics, and the ones putty cannot yet compute GET

Every metric `build-plan-artsy.md` §8 names, as one of two shapes. **`measured[]`** carries a number, the definition of what that number counts, the window it covers, and the table it was read from. `value` on a money metric is the count of ledger ENTRIES; the amount is `amountUsd`, a decimal string, because the column is `TEXT` and the sum is computed in Postgres' `NUMERIC` rather than in JavaScript. A `value: 0` with a `sourceRows: 0` is a real measurement of an empty table — a genuine zero, not a gap. **`notComputable[]`** carries no number. It names the specific missing data in `missing[]` and says why in `reason`. **A metric in this list is not a zero**, and rendering it as `0` claims that nobody did the thing, when the truth is that putty has not recorded whether they did. Today this list holds seven of §8's nine metrics, including the north star: `north_star_monthly_active_projects` needs a record of a project *changing* after creation, and no table in this schema stores one. **Availability is not a zero either.** If a measured metric's query fails, this route answers `500` rather than quietly downgrading that metric to `not_computable`, so a database outage never reads as a claim about the product. **Coverage on `launches_by_venue`.** A row is written when a launch is *requested* (`status: "awaiting_signature"` at create), so the counts are launch *attempts* by venue, not successful launches. Only `erc20-direct` — putty's own rail — can produce a row today: `pons-v2`, `hookr`, `orbio` and `venue-adapter` are registered providers that throw `ProviderBlockedError` from `buildLaunch`, so a launch through them is refused before a row exists. Every registered venue is listed, and a blocked venue is reported at zero *with its reason*, so a blocked rail is never presented as a rail nobody chose. Read `coverageNote` on the metric. **This is not `src/modules/observability/`.** That module is distributed tracing — Sentry spans for latency and the operator's health view. A span is one timed operation, not a count of anything a user did, and no metric here is answered from one. **The window.** Omit `days` for all time, which is the default and the honest one: on a young deployment a 30-day window is a window over very few rows, and a number computed from three reads like a rate. Every metric in the response is read over the same window, and each entry repeats it so it stays meaningful on its own. **Public and unauthenticated.** These are aggregate counts over rows this platform wrote about itself, and §5's Leg 2 asks for the buyback figure to be visible. No metric here names a user, an address, or a token. The operator's own health view is a different route behind a different gate: `GET /operator`.

Serve a public object by key GET

Returns the bytes of a public object with `Cache-Control: public, max-age=31536000, immutable`. The path captures the key after the `public/` prefix (e.g. `/public/tokens/<chain>/<address>/logo.png`). A key that does not exist in storage returns 404. The route is rate-limited per IP and unauthenticated; private objects are reachable only through the signed-url route on the blob store.