Developers

1. Authentication and scopes

Create a key in Settings → API keys (`orb_live_…`). Send it as `Authorization: Bearer …` or `X-Api-Key`. Keys are hashed at rest; the plaintext is shown once. Limit: up to 10 keys per Scale account. Rate limit: 60 requests per minute per key (shared across REST and MCP).
Scopes are hierarchical: read ⊂ write ⊂ action. Read covers GET surfaces; write adds webhook configuration; action adds Monitoring run-now. Sensitive use is audited on the account.

2. REST API v1

Base path: /api/v1. OpenAPI: /api/v1/openapi.json.
Read: integrations, mismatches, monitoring alerts, product search, comparison summaries, webhook status.
Write (`write` scope): `PUT /api/v1/webhooks` — set HTTPS URL, enable/disable, rotate HMAC secret.
Action (`action` scope): `POST /api/v1/monitoring/run` — trigger a Monitoring compare (optional `pairId`).

3. MCP server

Remote Model Context Protocol at /api/mcp (Streamable HTTP, JSON responses). Same API key auth. OAuth is coming soon.
Tools: `list_integrations`, `list_mismatches`, `get_monitoring_alerts`, `find_product`, `get_comparison_summary`, `get_webhook_config`, `configure_webhook` (write), `run_monitoring` (action).
`GET /api/mcp` returns discovery metadata without a key; `POST` runs JSON-RPC (`initialize`, `tools/list`, `tools/call`, `ping`).

Connect AI — Cursor, Claude, VS Code →

4. Webhooks and events

Subscribe in Monitoring settings or via `PUT /api/v1/webhooks` / MCP `configure_webhook`. Orbilyn POSTs JSON to your HTTPS URL with headers `X-Orbilyn-Event` and `X-Orbilyn-Signature` (`sha256=` HMAC-SHA256 of the raw body).
Events: `catalog.duplicate.new`, `catalog.drift.status` (channel status drift, e.g. BaseLinker ↔ Allegro), `sync.failure`, plus monitoring helpers `monitoring.mismatch.new`, `monitoring.alert`, `integration.health.broken`. Body always includes `text` (Slack-compatible) and `event`.

5. Connect clients + llms.txt

Point a remote MCP / HTTP connector at `https://app.orbilyn.com/api/mcp` and pass the Bearer (or X-Api-Key) header. Prefer the Connect AI guide for Cursor, Claude, and VS Code. If a host only supports OAuth today, that path is coming soon — use REST v1 with the same key meanwhile. Smoke test: POST `initialize`, then `tools/list`.
Machine-readable pointers: /llms.txt · discovery card: /.well-known/mcp.json.