Getting started

The base URL is https://developer.robotyx.systems/v1. Every request needs a Dome API key as a bearer token.

1. In the Dome app, open Developer · API (organisation admins only) and Create key. Copy the plaintext — it's shown once.
2. Call /v1/ping to confirm it resolves your account:

curl -H "Authorization: Bearer dome_sk_live_…" \
  https://developer.robotyx.systems/v1/ping
# { "ok": true, "account_id": "your-org", "environment": "live", "scopes": [ … ] }

Authentication & keys

Send Authorization: Bearer dome_sk_… on every request. Keys are stored hashed; the plaintext is shown once. A revoked key stops working immediately.

Scopes

Each key carries scopes; an endpoint returns 403 if the scope is missing.

assets:read · assets:write · sites:read · drilling:read · drilling:write · procurement:read · procurement:write · uns:read · maintenance:read · rca:read · crm:read · crm:write · keys:read

Environments

Keys are live or test. Both hit the same API; use test keys in CI and scripts.

Isolation

Every call is filtered to the key's account. One organisation's key can never read another's data.

Rate limits & errors

Default 120 requests/minute per key. Each response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds). Over the limit returns 429 with Retry-After.

Errors use a consistent envelope:

{ "error": { "code": "forbidden", "message": "Missing scope: assets:read" } }

Pagination

List endpoints take ?limit (default 50, max 200) and an opaque ?cursor. Responses return { "data": [ … ], "next_cursor": "…"|null }; pass next_cursor back to get the next page.

curl -H "Authorization: Bearer $DOME_API_KEY" \
  "https://developer.robotyx.systems/v1/assets?limit=100&cursor=eyJvIjoxMDB9"

MCP server

A remote Model Context Protocol server at https://developer.robotyx.systems/mcp, authenticated with your Dome API key and scoped to its account. Tools wrap the /v1 API (list_assets, get_asset, list_drilling_tools, list_sites, list_purchase_orders, query_uns, and create_purchase_request when the key has write scope).

Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "dome": {
      "url": "https://developer.robotyx.systems/mcp",
      "headers": { "Authorization": "Bearer dome_sk_live_…" }
    }
  }
}

A stdio shim (npm i -g @robotyx/dome-mcp, env DOME_API_KEY) is published for clients that only speak stdio. Ships in a following release.

CLI

npm i -g @robotyx/dome
dome auth login          # paste your dome_sk_ key
dome assets ls --class "Drilling Tool"
dome drilling ls
dome po ls
dome keys ls
# add --json to any command for machine-readable output

Honors DOME_API_KEY and DOME_BASE_URL. Ships in a following release.

Changelog

• v1 — API keys + /v1/ping; read endpoints (assets, sites, drilling-tools, uns/points, crm, procurement, keys); POST /v1/purchase-requests (draft MR, procurement:write); OpenAPI 3.1; per-account isolation; 120/min rate limit. In-app Developer view, remote MCP server (/mcp) and the @robotyx/dome CLI.