Skip to content
Machinaut
Open the console

Reference

API reference

The Machinaut control-plane HTTP API, grouped by area. Every route carries an honest status — shipped, beta, or planned — and its auth. It mirrors the endpoint map the control plane serves at its own GET / root, so it tracks what's actually running.

Statuses are honest — and some surfaces are planned, not live

Shipped: ingest, the explorer, sharing, email + password auth, API tokens, and the sample sandbox. Beta: the approval inbox / relay, calibration, sentinels, overview, audit, policies (draft + impact-simulation), team / roles, and the v0.3.0 enterprise surfaces — OIDC SSO, SCIM 2.0, verified domains, and the Fleet map. Planned (do not build against these as if live): SAML, magic-link, password reset, managed approver keys, a Machinaut CLI / SDK, Desktop, and email transport — invites are copy-links, and no email is sent. Two things the console surfaces but does not yet do: managed key custody (the selector is refused — custody is customer-held at every tier) and Fleet’s spend / drift columns (no metering or drift baseline exists, so they return null). The always-current per-capability state is the roadmap, and the live console is the source of truth.

Authentication

Four ways a request is authenticated. A bearer token is checked first; a session cookie is the browser fallback.

  • Bearer — a machine API token (mk_…), project- or tenant-scoped, minted under POST /v1/tokens. Sent as Authorization: Bearer … or x-api-key. This is what the shipper and the approval proxy use.
  • Session — a browser session cookie (mc_session) from signup / login. Many routes are session-only (tokens, org, identity, the Fleet map, the sample sandbox, share management): a machine credential — even a leaked one — can’t reach them. Session · owner additionally re-checks a live owner membership on every call, so a deprovisioned owner loses access immediately.
  • SCIM bearer — a separate provisioning credential (scim_…), minted per org and stored only as a hash. It authenticates your IdP against /scim/v2/… and nothing else — it cannot read sessions, chains, or approvals.
  • Public — no auth: the ops probes, the OIDC start/callback, and a shared session’s public read. Internal marks probes not exposed through the Ingress at all.
the two credential headershttp
# Machine callers (shipper, approval proxy) — checked first
Authorization: Bearer mk_live_…        # or:  x-api-key: mk_live_…

# Browser callers (the explorer) — a session cookie from signup/login
Cookie: mc_session=…

Endpoints

Grouped by area. :param segments are path parameters; a GET | PUT cell means the same path serves both verbs.

Health & ops

Unauthenticated operational probes. Readiness and metrics are internal — never routed through the Ingress.

EndpointDescriptionStatusAuth
GET/healthz
Liveness — the process is up.ShippedPublic
GET/readyz
Readiness — 200 when the backing store is reachable, 503 when not.ShippedInternal
GET/metrics
Prometheus metrics — request counts + latency.ShippedInternal

Ingest

The session_ship@1 receiver — full wire format in the ingest contract.

EndpointDescriptionStatusAuth
POST/v1/events
Ingest a shipped session (NDJSON manifest + records).ShippedBearer

Explorer & sessions

Read the hosted chain — projects, sessions, and a session’s six-stage projection + report.

EndpointDescriptionStatusAuth
GET/v1/projects
List a tenant's projects.ShippedBearer / session
GET/v1/projects/:project_id/sessions
List a project's sessions.ShippedBearer / session
GET/v1/projects/:project_id/sessions/:session_id
A session’s chain projection + report.ShippedBearer / session

Sharing

Mint and revoke public post-mortem links. The public read needs no auth; managing links is session-only.

EndpointDescriptionStatusAuth
POST/v1/projects/:project_id/sessions/:session_id/shares
Mint a public post-mortem link.ShippedSession
GET/v1/projects/:project_id/sessions/:session_id/shares
List a session's share links.ShippedSession
DELETE/v1/shares/:id
Revoke a share link.ShippedSession
GET/v1/shares/:token
Public read — a shared session’s chain + report, no auth.ShippedPublic

Calibration

OSS-computed ECE / Brier, charted per session and rolled up per fleet.

EndpointDescriptionStatusAuth
GET/v1/projects/:project_id/calibration
Fleet calibration — the latest pass per session.BetaBearer / session
GET/v1/projects/:project_id/sessions/:session_id/calibration
Session calibration passes.BetaBearer / session

Sentinels

The agent SIEM — OSS-raised sentinel alerts, hosted and rolled up.

EndpointDescriptionStatusAuth
GET/v1/projects/:project_id/sentinels
Fleet sentinel rollup across sessions.BetaBearer / session
GET/v1/projects/:project_id/sessions/:session_id/sentinels
Session sentinel alerts.BetaBearer / session

Fleet, overview & audit

Rollups the single-operator OSS viewer can’t give. /v1/overview and /v1/audit are scoped to one org; /v1/fleet (new in v0.3.0) is the multi-org lens — it spans the orgs you are already a member of, and adds no reach beyond that.

EndpointDescriptionStatusAuth
GET/v1/overview
Org overview — sessions/day, held rate, calibration health, sentinel feed, top agents.BetaBearer / session
GET/v1/audit
Audit log — approve/deny/run/block decisions with retained proof; ?format=csv|ndjson to export.BetaBearer / session
GET/v1/fleet
The multi-org health map — per-org rollup, worst-first agent table, and a 14-day activity chart across every Team/Enterprise org you govern. Session-only by design: an API token is single-tenant, so a machine credential structurally cannot make the cross-org read. Free orgs are returned in excludedOrgs rather than a 402. Reports spend and drift as null — neither is built.BetaSession

Policies

Read the active signed policy and edit the unsigned draft. The cloud never signs — you sign and deploy locally.

EndpointDescriptionStatusAuth
GET/v1/policies
Active (signed) policy snapshot, read-only.BetaBearer / session
GET | PUT/v1/policies/draft
The team’s unsigned working draft.BetaBearer / session
POST/v1/policies/draft/impact
Indicative flip simulation (best-effort; the authoritative dry-run is local).BetaBearer / session
GET/v1/policies/draft/export
Export the draft as unsigned canonical Policy JSON to sign + deploy.BetaBearer / session

Approvals

The relay (announce / fetch / consume) and the write-path (inbox / resolve) — full semantics in the approval relay contract.

EndpointDescriptionStatusAuth
POST/v1/approvals
announce — park a hold (bare ApprovalRequest or wrapper).BetaBearer
POST/v1/approvals/:project_id
announce with project in the path.BetaBearer
GET/v1/approvals/inbox
Approval inbox — held actions with status + resolution summary.BetaBearer / session
POST/v1/approvals/:project_id/:request_id/resolve
Record a signed Approve / Deny.BetaBearer / session
GET/v1/approvals/:project_id/:request_id
fetch — the untrusted ApprovalResolution, or 404.BetaBearer
DELETE/v1/approvals/:project_id/:request_id
consume — spend the resolution (tombstoned).BetaBearer

Auth

Email + password, plus OIDC SSO in beta (v0.3.0) — a deployment must have a secret-encryption key configured before an SSO connection can be stored, so a self-host without one reports SSO as unconfigured. SAML, magic-link, and password reset are planned, not shipped.

EndpointDescriptionStatusAuth
POST/v1/auth/signup
Email + password signup → session cookie.ShippedPublic
POST/v1/auth/login
Email + password login → session cookie.ShippedPublic
POST/v1/auth/logout
End the session ({ all: true } = everywhere) and clear the cookie.ShippedSession
POST/v1/auth/switch-org
Switch the active org for a multi-org user → the me payload for the new org.ShippedSession
GET/v1/auth/me
Current user + org.ShippedSession

API tokens

Mint and revoke the machine tokens that authenticate ingest and the relay. Session-only — a leaked machine key must never mint another.

EndpointDescriptionStatusAuth
GET/v1/tokens
List the tenant's API tokens.ShippedSession
POST/v1/tokens
Mint a project/tenant API token — secret shown once.ShippedSession
DELETE/v1/tokens/:id
Revoke an API token.ShippedSession

Org & team

Members, roles, and invites. Invites are copy-able capability links — no email is sent (email transport is planned). Session-only; role/invite changes are owner-only.

EndpointDescriptionStatusAuth
GET/v1/org/members
Org roster — members + roles.BetaSession
PATCH/v1/org/members/:id
Change a member's role (owner | member).BetaSession · owner
DELETE/v1/org/members/:id
Remove a member.BetaSession · owner
POST/v1/org/invites
Invite a teammate → a copy-able link, no email sent.BetaSession · owner
GET/v1/org/invites
Pending invites with their links.BetaSession · owner
DELETE/v1/org/invites/:id
Revoke a pending invite.BetaSession · owner
GET/v1/org/invites/lookup/:token
Preview an invite before accepting.BetaSession
POST/v1/org/invites/accept
Redeem an invite — email-bound.BetaSession
GET/v1/org/audit
Append-only admin audit log — member add/remove and role changes, with actor, before/after and request-id.BetaSession · owner
GET/v1/org/settings
Governance settings — enforce-SSO, the org’s plan and unlocked capabilities, and the key-custody default. Custody reads customer_held at every tier.BetaSession · owner
PATCH/v1/org/settings
Toggle enforce-SSO (Team+). Selecting managed key custody is refused with 409 custody_managed_unavailable — the selector is surfaced, but managed custody is planned, not built, and customer-held stays in force.BetaSession · owner
GET/v1/org/seats
The billable-identity contract — live memberships vs pending invites vs deactivated, plus the org’s plan. No metering or billing is wired up yet.BetaSession · owner

Single sign-on (OIDC)

New in v0.3.0. SSO governs who may sign in, never who may sign — an SSO-granted owner holds console authority, not signing authority, because approver keys stay customer-held. The IdP client secret is sealed at rest (AES-256-GCM), so a deployment without a secret-encryption key configured reports SSO as unconfigured rather than storing it in the clear. SAML is planned, not built.

EndpointDescriptionStatusAuth
GET/v1/org/sso
The org’s OIDC connection (the client secret is never returned) plus the SP callback URL to register at your IdP.BetaSession · owner
POST/v1/org/sso
Configure the OIDC connection — discovery URL, client id/secret, and IdP group → role mapping. Requires the Team plan.BetaSession · owner
PATCH/v1/org/sso
Edit the connection — rotate the client secret or change the group → role map.BetaSession · owner
DELETE/v1/org/sso
Disable the org’s OIDC connection.BetaSession · owner
GET/sso/:org_id/oidc/start
SP-initiated login → redirect to the IdP. ?mode=test previews the decoded claims and the role you’d get without minting a session.BetaPublic
GET/sso/:org_id/oidc/callback
The OIDC redirect URI — validates state/nonce, verifies the id_token, JIT-provisions the user, and mints an SSO session.BetaPublic

SCIM 2.0 provisioning

New in v0.3.0. Your directory keeps the org roster in sync. Deprovisioning a leaver kills their console sessions and revokes their personal API tokens — but it cannot rotate a customer-held approver key; that stays a customer-side operation. Minting a token requires the Enterprise plan and a live SSO connection.

EndpointDescriptionStatusAuth
GET/v1/org/scim/tokens
List the org’s SCIM bearer tokens.BetaSession · owner
POST/v1/org/scim/tokens
Mint a SCIM bearer — shown once, stored only as a SHA-256 hash. Requires the Enterprise plan.BetaSession · owner
POST/v1/org/scim/tokens/:id/rotate
Rotate a SCIM token — mints a successor while the old one stays valid for an overlap window.BetaSession · owner
DELETE/v1/org/scim/tokens/:id
Revoke a SCIM token.BetaSession · owner
GET|POST|PUT|PATCH|DELETE/scim/v2/Users…
The SCIM 2.0 user endpoints your IdP drives (plus /scim/v2/ServiceProviderConfig). Setting active: false deprovisions immediately; reactivating flips the same row back, so no phantom seat is created. SCIM-managed members take precedence over manual and JIT.BetaSCIM bearer

Verified domains

New in v0.3.0. Claim a domain, prove control with a DNS-TXT record, and optionally let teammates on it auto-join on their first SSO sign-in. Claiming and verifying work on any tier; only enabling auto-join needs Team+. Auto-join is exact-match only — a verified acme.com does not authorize eng.acme.com — and it admits a user only when your own IdP asserts email_verified, so it fails closed.

EndpointDescriptionStatusAuth
GET/v1/org/domains
List this org’s domain claims and their verification state.BetaSession · owner
POST/v1/org/domains
Claim a domain → returns the DNS-TXT record to publish.BetaSession · owner
POST/v1/org/domains/:id/verify
Check the TXT proof and stamp the domain verified.BetaSession · owner
PATCH/v1/org/domains/:id
Toggle auto-join (enabling requires a verified domain and the Team plan). Default off.BetaSession · owner
DELETE/v1/org/domains/:id
Remove a domain claim.BetaSession · owner

Sample sandbox

One-click sample project for onboarding — see connect your agent. Session-only: a machine credential must never seed or wipe a tenant.

EndpointDescriptionStatusAuth
GET/v1/demo
Whether the sample project is seeded (fingerprint-verified).ShippedSession
POST/v1/demo/seed
Load a labelled sample — a real chain + held approval + audit trail.ShippedSession
DELETE/v1/demo
Remove the sample project.ShippedSession

This map comes from the running control plane

Hitting GET / on a live Machinaut returns its own endpoint map — each route with its status inline — and this reference mirrors it. Two v0.3.0 routes (/v1/fleet and /v1/org/domains) are not in that root map yet, so they are documented here from the routes the server actually registers; the server, not this page, is the source of truth. The two write contracts have their own pages: the ingest contract and the approval relay contract.