API overview

The dashboard, the website and the agents all speak the same API.

Base URL

https://api.infrality.io/api

The live channel is a WebSocket at wss://api.infrality.io/api/ws. Health is at https://api.infrality.io/health.

Note

The API is what Infrality’s own clients use. Its shapes can change between releases; the interactive API reference is not published in production. The agent routes below are the stable surface for integrations.

Authentication

Caller	How
An agent	x-api-key: nk_… — an API key of its organization
A person	A session from signing in, held by the dashboard and website in an httpOnly cookie
A directory	Authorization: Bearer scim_… — a provisioning token, on /api/scim/v2 only

Errors

Errors are JSON:

{ "statusCode": 403, "message": "Only an owner or admin can do that" }

• 4xx messages are meant to be read: they say what was wrong.
• 5xx answers are one sentence; the details are logged on our side.
• Every refusal is a 403, never a 404 — an id you may not see looks like one that does not exist.
• A refusal because of a plan limit carries code: "plan_limit" or "plan_feature" and says which plan lifts it.
• A refusal because of an organization’s security policy carries policy: { organizationId, requirement }.

Rate limits

100 requests a minute per address overall, and tighter limits on sensitive routes — sign-in (5 a minute), password reset and invitations (3 per ten minutes), share links and SSO discovery (10 a minute). Past a limit the answer is 429 with a one-sentence message; wait and retry.

Body size

256 KB per request, except board saves and agent ingest, which carry a topology.