API Overview

The run API is how your own server or interface starts and talks to runs of a published loop. Every path begins with /api on https://plutonium.io. A loop is named by its public id (pl_…), shown on the loop’s Keys tab once the loop is published.

Authentication

Every call carries one header:

Authorization: Bearer <credential>

The credential is one of two things. A console session cookie is refused on the run routes.

• An API key (rk_…) for your server. An owner mints it on the loop’s Keys tab (POST /api/loops/{loopId}/keys) with one or more scopes: create_runs, read_runs and read_collections. The key text is shown once and cannot be shown again; revoke it and mint another if it is lost. A key’s scopes must be ones the loop’s delivery allows. A read_collections key names the API it serves: choose it under Serves on the loop’s Keys tab, press the Mint a key for button in the API’s detail on Schedules, or send claim_name when you mint it through the API.
• A user token for one of your users, minted by one of the loop’s identity doors. The loop’s identity scheme decides which door it has.

Limits

Routes are rate limited, and a refused request answers 429 Too Many Requests with a sentence that names which limit and a Retry-After header with the seconds to wait. There are several:

• Each route’s own limit, per account and across all callers.
• The loop’s per-address limit, on the identity doors and on starting a run.
• The loop’s per-subject run cap and its concurrent-run cap, on starting a run.

A route that spends money refuses with 503 rather than let a request through when its limit cannot be checked.

The reference

• Identity: the doors that mint a user token, and your own OpenID issuer.
• Runs: start a run, read it, talk to it, follow it.
• Search: search what a loop searches.
• Collections: read a collection’s records from your server.
• Webhooks: start a run with a signed request, and receive a loop’s outputs.