API clients and listings

Running a RequestScript request used to mean running your own node, or knowing a node’s API_KEY. API clients remove both. An organization creates an API client for one node on the Stellarium Platform, exchanges it for a short-lived run token, and calls the node’s POST /v1/run with that token.

On your own nodes, runs are free, just as with the node’s API key.
On another organization’s listed node, runs are paid from your organization’s prepaid balance: the node’s price per script token, plus every paid function the script calls.

All amounts are micro-USD, as in Payments.

Listing a node

A listed node appears on the platform’s Explore page, and any organization can create API clients for it. On the Nodes page, an admin sets each node’s listing:

Field	Purpose
Name and description	What callers see on Explore
Price per million tokens	What a run pays per million script tokens it executes. `0` is free
Listed	Whether other organizations can run scripts on it

Listing needs the node’s URL. A node reports its BASE_URL to the operator whenever it starts with OPERATOR_URL set. When you list it, the operator calls {BASE_URL}/v1/self and lists the node only if it answers with the node’s public key. If the node later reports a different URL, it is unlisted until you list it again. You earn the token charges and your paid functions’ prices, less the 20% platform fee, like any paid call. A priced node’s organization must have finished payout setup before its runs are accepted.

Creating an API client

On the API clients page, or from a node’s Create API client button on Explore, an admin chooses:

Field	Purpose
Node	One of your nodes, or a listed node
Max per run	The most one run may cost, its script tokens and its paid calls together. Defaults to $1
Monthly cap	Optional. The most the client’s runs may cost in a calendar month (UTC)

The client’s ID (cli_...) and secret (cs_...) are shown once: the operator keeps only a hash of the secret. Revoke a client on the same page, and it can’t get new tokens or start new runs.

Running a script

Exchange the client for a run token at the operator’s token endpoint. It is the OAuth 2.0 client credentials grant, so most OAuth libraries work too:

TOKEN="$(curl -s -X POST https://operator.stellarium.sh/v1/oauth/token \
  -d grant_type=client_credentials -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" \
  | jq -r .access_token)"

curl -X POST https://node.example.com/v1/run \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"source": "request GetTemperature {\n  const weather: com.example.Weather\n\n  return weather.temperature(city: \"Oslo\")\n}"}'

Response

{ "returnValue": { "value": 12, "error": null }, "usage": { "tokens": 17 } }

A run token lasts 15 minutes. Reuse it for many runs, and get a new one when it expires. The token names its node as its audience, so no other node accepts it.

Stellarium Explorer runs requests as an API client too: set the node, the operator URL, the client ID and its secret in a workspace’s network settings. It gets and renews tokens for you, and shows each request’s most and actual script tokens.

Script tokens

A node prices scripts by the tokens they execute. A token is one lexer token of RequestScript: an identifier, keyword, number, operator or punctuation mark, or a whole string literal however long. Only what runs is counted:

An if counts each condition it evaluates, and then only the branch it takes. Untaken branches cost nothing.
The side of && or || that a short circuit skips is not counted.
The request declaration and the body’s outer braces are free.

Because RequestScript has no loops, the most tokens a script can execute is known before it runs. The operator computes it from the script itself. A run’s token charge is ceil(tokens × price / 1,000,000) micro-USD. See the RequestScript docs for the exact rules.

How a billed run works

The node checks the run token’s signature against the operator’s published keys, and that it is addressed to this node and unexpired.
The node asks the operator to authorize the run. The operator computes the script’s most tokens, and holds up to the client’s maximum per run on your available balance. The hold is less when your balance or monthly cap leaves less, but it always covers the script’s tokens at the node’s price.
The script runs. Each paid function it calls, on another node or on this one, is paid with a voucher that names the run. The operator moves the call’s amount from the run’s hold to the call, so a run can never cost more than its hold. Calls are charged at their manifest prices, exactly as in Payments.
The node captures the run with the tokens the script executed. You’re charged for them at the node’s price, and the rest of the run’s hold is released. A script that fails partway is charged for what it executed. A run that the node itself fails to complete is released and costs nothing.

If the operator refuses the run, the script doesn’t run, and the node answers with the operator’s status:

Status	Reason
`401`	The token is invalid or expired, or its client was revoked
`402`	The script may cost more than the client’s maximum per run, the balance can’t cover it, or the monthly cap is reached
`403`	The node was unlisted or revoked, or your organization is frozen
`422`	The node’s organization can’t receive payouts yet
`503`	The operator couldn’t be reached

Your runs and what each was charged appear on the Usage page under Runs spent, and the paid calls they made under Spent. A listed node’s organization sees them under Runs earned and Earned.

Operator routes

Route	Called by	Purpose
`POST /v1/oauth/token`	API clients	Exchanges `client_id` and `client_secret` (in the body or with HTTP Basic) for `{ access_token, token_type, expires_in }`. Refusals follow OAuth: `invalid_client` (401), `unauthorized_client` (400) for a frozen organization or a node that’s no longer available
`GET /v1/.well-known/jwks.json`	Nodes	The public keys run tokens are signed with (EdDSA)
`POST /v1/runs/authorize`	Nodes	`{ token, runId, source }`. Holds the run’s cost
`POST /v1/runs/capture`	Nodes	`{ runId, tokens }`. Charges the tokens, capped at the script’s most, and releases the rest
`POST /v1/runs/release`	Nodes	`{ runId }`. Frees the run’s hold without charging

A run token’s claims are iss (stellarium), sub (the client ID), aud (the node’s public key), org (the paying organization), iat, exp and jti.

Limits

Token counts come from the node. The operator caps them at the most the script can execute, which it computes itself, but within that cap it trusts the node, as it trusts usage reported by inference functions.
Revoking takes effect at the next run. A revoked client’s existing token still verifies at the node until it expires, but billed runs are refused because the operator checks the client on every run.
Price changes apply to new runs. A run is charged at the price the node had when the run was authorized.

Getting Started

Concepts

Running a node

Standard Library

Inference

Community

API clients and listings

Listing a node

Creating an API client

Running a script

Script tokens

How a billed run works

Operator routes

Limits

​Listing a node

​Creating an API client

​Running a script

​Script tokens

​How a billed run works

​Operator routes

​Limits

Listing a node

Creating an API client

Running a script

Script tokens

How a billed run works

Operator routes

Limits