HTTP API

All routes are mounted under /v1.

Public routes

`GET /v1/`

Liveness check.

{ "hello": "world" }

`GET /v1/self`

This node’s identity, used by peers when bootstrapping.

{ "baseUrl": "http://127.0.0.1:3000", "publicKey": "<SIGNING_PUBLIC_KEY>", "name": "http://127.0.0.1:3000" }

`GET /v1/peers`

Peers stored on this node.

{ "peers": [{ "baseUrl": "http://127.0.0.1:3002", "name": "http://127.0.0.1:3002", "publicKey": "..." }] }

`GET /v1/resources`

Resources this node knows about. Each entry includes path, name, baseUrl, and functions with name, returnType, parameters, and paymentManifest (costLamports, recipientAddress) when the function is paid.

Running requests

`POST /v1/run`

Runs one RequestScript request. Requires Authorization: Bearer <API_KEY>.

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

Status	Body	When
`200`	`{ "returnValue": ... }`	The request ran
`400`	`{ "error": "Invalid script" }`	The script’s declaration is not a `request`
`401`	`{ "error": "Authorization header is required" }` or `{ "error": "Invalid API Key" }`	Missing or wrong API key
`500`	`{ "error": "Internal server error" }`	Any other failure

Node-to-node routes

These routes are called by other nodes. You don’t normally call them yourself.

`PUT /v1/peers`

A peer announces itself. Body: { baseUrl, name, publicKey, signature, expiry }. The signature covers { baseUrl, name, expiry }.

`PUT /v1/all-resources`

A known peer broadcasts its internal resources. Body: { publicKey, resources, signature, expiry }. The signature covers { resources, expiry }. Responds 400 if the peer is unknown, the signature is invalid, or expiry has passed.

`POST /v1/run/resource`

Calls one function on a resource hosted by this node.

{
  "resourcePath": "com.example",
  "resourceName": "Weather",
  "functionName": "temperature",
  "parameters": [{ "name": "city", "value": "Oslo" }],
  "paymentVoucher": { "...": "optional, see Payments" }
}

If paymentVoucher is present, the node verifies its signature before running the function (400 Invalid payment voucher on failure), then submits it to the operator for settlement after a successful call. See Payments.

Getting Started

Concepts

Running a node

Community

Public routes

`GET /v1/`

`GET /v1/self`

`GET /v1/peers`

`GET /v1/resources`

Running requests

`POST /v1/run`

Node-to-node routes

`PUT /v1/peers`

`PUT /v1/all-resources`

`POST /v1/run/resource`

​Public routes

​GET /v1/

​GET /v1/self

​GET /v1/peers

​GET /v1/resources

​Running requests

​POST /v1/run

​Node-to-node routes

​PUT /v1/peers

​PUT /v1/all-resources

​POST /v1/run/resource

Public routes

`GET /v1/`

`GET /v1/self`

`GET /v1/peers`

`GET /v1/resources`

Running requests

`POST /v1/run`

Node-to-node routes

`PUT /v1/peers`

`PUT /v1/all-resources`

`POST /v1/run/resource`