API reference overview

peaqOS exposes two HTTP/JSON APIs:

MCR API: read-only. , machine profiles, operator fleet data, metadata, and Machine Cards, all backed by contracts on peaq. Documented below.
Machine Markets API: powers Scale. Machine identity proofs, machine records, , the skill registry, the service catalogue, and machine-aware market search. See the Machine Markets API overview.

This page covers the MCR API. Writes against peaqOS state (, event submission, ) happen via the peaqOS SDK and .

Quick start

Pick the setup that matches your workflow: an AI-driven flow via the peaqOS skill, or direct HTTP calls.

Agent skill
cURL
ROS 2

pip install peaq-os-cli
npx skills add peaqnetwork/peaq-os-skills

Auto-detects Claude Code, Cursor, or Windsurf. Then invoke /peaqos in Claude Code and ask for an MCR score, machine profile, or operator fleet — the skill picks the right CLI command and the CLI hits this API for you. To target a specific runtime, add --agent claude-code | cursor | windsurf — see the peaqOS AI page.

curl https://mcr.peaq.xyz/mcr/did:peaq:0xabc123...

Endpoint index below. No API key required: MCR data is public.

ros2 service call /peaqos_node/mcr/query \
  peaq_ros2_interfaces/srv/PeaqosQueryMcr \
  "{did: 'did:peaq:<MACHINE_EVM_ADDRESS>'}"

peaq_ros2_peaqos exposes the MCR API as ROS 2 services. Full reference on SDK: ROS 2; MCR-specific services are listed under Services → MCR queries.

Base URL

Set the environment variable PEAQOS_MCR_API_URL to the root of the MCR API server:

export PEAQOS_MCR_API_URL=https://mcr.peaq.xyz

For local development against a self-hosted server, use http://127.0.0.1:8000. All endpoint paths in this reference are relative to that base URL.

Authentication

The MCR API is a public read API. No API keys, tokens, or signatures are required. MCR scores, machine profiles, and metadata are public on-chain data.

Rate limits

The API enforces a limit of 90 requests per minute per IP address. Requests that exceed the limit receive a 429 Too Many Requests response. For production deployments with multiple workers, the rate limiter backend can be swapped to Redis.

Server configuration

When self-hosting the MCR API, these environment variables tune caching, storage, and test-mode behavior. Typical deployments only need the contract addresses and RPC; the rest have sensible defaults.

Variable	Default	Purpose
`IDENTITY_REGISTRY_ADDRESS`	n/a	Primary contract address. When empty, the server boots in test mode: `/ready` returns 503 with `rpc_connected: false` and all `contracts.*` (including `admin_flags`) reported as `false`.
`ADMIN_FLAGS_ADDRESS`	n/a	Optional `AdminFlags` contract. Influences MCR responses via `negative_flag` and admin trust overrides. When the service is initialised but this address is unset, `contracts.admin_flags` on `/ready` is `true`: the probe skips the optional check and the service stays ready.
`MCR_CACHE_TTL`	`3600`	MCR response cache TTL in seconds. Set to `0` to disable caching entirely.
`EVENT_STORE_DB_PATH`	`/tmp/peaqos_events.db`	SQLite path for the delta-sync event cache. Must resolve under `/tmp`, `/data`, or `/var/lib/peaqos`.
`SKIP_PROVISIONED_GATE`	`false`	Dev/demo toggle that short-circuits the “must be bonded” gate on scoring. Never enable in production.

Error envelope

Every error response uses the same JSON shape:

{
  "detail": "<human-readable message>"
}

The detail string describes the cause. Common values:

`detail` value	Meaning
`"Service not initialised"`	Server started without contract addresses (test mode)
`"Chain unavailable"`	RPC call to the node or a contract failed
`"Empty DID"`	DID path parameter is empty
`"Invalid Ethereum address format"`	DID or address does not match `^0x[a-fA-F0-9]{40}$`
`"Machine DID not found"`	DID address has no `machineId` attribute in the DID registry
`"Machine not registered"`	Machine ID is not present in the IdentityRegistry contract
`"Machine not found"`	Machine ID does not exist (machines endpoint)
`"Machine wallet not found"`	Machine wallet is the zero address
`"Token not found"`	NFT token ID does not map to any machine in MachineNFT
`"Internal server error"`	Unhandled exception (logged server-side)

Status codes

Code	Meaning
`200 OK`	Request succeeded; JSON body returned
`400 Bad Request`	DID is empty or the address does not match `^0x[a-fA-F0-9]{40}$`
`404 Not Found`	The requested DID, machine ID, or token ID does not exist on-chain
`422 Unprocessable Entity`	Path or query parameter failed validation (FastAPI auto-generated)
`429 Too Many Requests`	Rate limit exceeded. Responses include slowapi headers (`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`)
`500 Internal Server Error`	Unhandled server exception
`503 Service Unavailable`	Service not initialised or chain/RPC call failed

DID format

Endpoints that accept a DID path parameter support two formats:

Full DID: did:peaq:0xabc123...
Raw address: 0xabc123...

The server strips the did:peaq: prefix internally before querying the chain.

MCR API endpoints

GET /mcr/{did}

Machine Credit Rating score, rating, bond status, event counts, and revenue trend for a single machine.

GET /machine/{did}

Full machine profile with data visibility-dependent fields (private, onchain, or public).

GET /operator/{did}/machines

Paginated list of machines registered under an operator, with per-machine MCR scores.

GET /metadata/{token_id}

NFT metadata for a MachineNFT token. Same response shape as /machine/.

GET /machines/{machine_id}

peaqOS Machine Card for a machine, including services, registrations, and operator info.

GET /health and /ready

Liveness and readiness probes for health checks and monitoring.

Machine Markets API

Separate surface, separate host (orchestrator deployment). Pairing, delegation policy, skill registry, service catalogue, and market search.

Machine Markets API overview

Base path, access model, error codes, common types, and the full Machine Markets endpoint surface.

​Quick start

​Base URL

​Authentication

​Rate limits

​Server configuration

​Error envelope

​Status codes

​DID format

​MCR API endpoints