HTTP operations — Ablative docs

Read the complete contract

Paths below are relative to the API mount. In a deployment serving its screens, the mount is the API prefix shown in the connection guide. Parameter braces identify values supplied by the caller; do not send the braces literally.

OpenAPI supplies request bodies, query parameters, response schemas and named refusals. Read that operation before assembling a request. Where an operation has no OpenAPI security entry, read its request contract for any credential or one-time proof it takes.

Read and reconcile

GET generally reads. Some read operations use POST for a structured request; the method alone does not determine whether an operation changes state. Follow the operation’s contract. When a changing operation’s outcome is uncertain, use its recorded operation and reconciliation route before trying again.

Identity and people

GET /agent/grants: The signed agent's own live grants and their chain admission. Requires route admission.
POST /agents: Register an agent. Requires route admission.
GET /agents/{id}: An agent the caller answers for. Requires route admission.
GET /agents/{id}/calls: An agent's model calls, newest first. Requires route admission.
GET /agents/{id}/calls/{call}: One model call whole: its record and both bodies. Requires route admission.
GET /agents/{id}/certificates: An agent's certificates. Requires route admission.
POST /agents/{id}/certificates: Issue a certificate. Requires route admission.
POST /agents/{id}/certificates/{serial}/withdrawal: Withdraw one. Requires route admission.
GET /agents/{id}/control-sessions: An agent's control session identities, stopped sessions included. Requires route admission.
GET /agents/{id}/goals: An agent's goals. Requires route admission.
POST /agents/{id}/goals: Set a goal on an agent. Requires route admission.
GET /agents/{id}/mcp-requests: An agent's MCP requests. Requires route admission.
POST /agents/{id}/mcp-requests: Ask for a declared MCP server. Requires route admission.
POST /agents/{id}/mcp-requests/{request}/approve: Approve an MCP request within remit. Requires route admission.
GET /agents/{id}/memory: An agent's memory. Requires route admission.
POST /agents/{id}/pass: An agent's pass to an approved app, carrying its own grants, asked with its run pass or a grant credential for a grant it holds. No OpenAPI security entry; the request contract still applies.
GET /agents/{id}/policy: An agent's tool-boundary policy. Requires route admission.
POST /agents/{id}/policy: Set an agent's tool-boundary policy, from its next launch. Requires route admission.
GET /agents/{id}/provisioning: An agent's profile. Requires route admission.
POST /agents/{id}/provisioning: Set an agent's profile. Requires route admission.
POST /agents/{id}/provisioning/{version}/review: Review a profile. Requires route admission.
GET /agents/{id}/refusals: An agent's refused tool calls. Requires route admission.
POST /agents/{id}/reports-to: Change an agent's reporting edge. Requires route admission.
POST /agents/{id}/restart: Restart an agent on its latest reviewed profile. Requires route admission.
GET /agents/{id}/runtime/sessions: An agent's runtime sessions. Requires route admission.
POST /agents/{id}/runtime/sessions/{session}/reports: A runtime report. Requires route admission.
POST /agents/{id}/start: Start an agent. Requires route admission.
POST /agents/{id}/start-command: An agent's start command. Requires route admission.
POST /agents/{id}/stop: Stop an agent. Requires route admission.
GET /agents/{id}/stops: An agent's stops. Requires route admission.
GET /agents/{id}/usage: An agent's budget crossings and what came of each. Requires route admission.
POST /agents/{id}/usage: Report a use an agent made. Requires route admission.
GET /agents/{id}/variables: An agent's variables. Requires route admission.
POST /agents/{id}/variables: Patch an agent's variables with the revision read. Requires route admission.
POST /agents/{id}/wake: Wake an agent's live session. Requires route admission.
GET /agents/{id}/words: An agent's slots resolved, and its own layer. Requires route admission.
POST /agents/{id}/words/{slot}: Set a slot at an agent's layer. Requires route admission.
GET /directory/agents/{id}: Any agent, for the administrator. Requires route admission.
GET /directory/people: Every person, for the administrator. Requires route admission.
GET /directory/people/{id}/account: A person's sign-in account. Requires route admission.
POST /directory/people/{id}/account/email: Change a person's email. Requires route admission.
POST /directory/people/{id}/account/enabled: Enable or disable a person's sign-in. Requires route admission.
POST /directory/people/{id}/account/password: Set a person's password. Requires route admission.
GET /directory/people/{id}/sessions: A person's sessions. Requires route admission.
POST /directory/people/{id}/sessions/{session}/end: End a session. Requires route admission.
GET /identities: Every identity the directory holds. Requires route admission.
GET /identities/{id}: One identity. Requires route admission.
POST /identities/{id}/profile: Change an identity's profile. Requires route admission.
POST /identities/{id}/transitions: Move an identity's state. Requires route admission.
POST /identity/estate-apply: Apply grants through the installed loader. Requires route admission.
GET /identity/estate-plan: Read the installed estate plan. Requires route admission.
POST /identity/import: Import named entries as an independently authorised service account. Requires route admission.
GET /people: The people the caller may see. Requires route admission.
POST /people: Register a person. Requires route admission.
POST /people/admit: Admit a person in one act: register, issuer account by email, bind, activate, first root grant. Requires route admission.
POST /people/{id}/logins: Bind a login to a person. Requires route admission.
GET /me: The signed-in caller. Requires route admission.
GET /me/account: The caller's sign-in account. Requires route admission.
POST /me/account/email: Change the caller's email. Requires route admission.
POST /me/account/password: Change the caller's password. Requires route admission.
GET /me/session/variables: The asking run's session variables, by its run pass. No OpenAPI security entry; the request contract still applies.
POST /me/session/variables: Patch the asking run's session variables, by its run pass. No OpenAPI security entry; the request contract still applies.
GET /me/variables: The asking run's agent variables, by its run pass. No OpenAPI security entry; the request contract still applies.
POST /me/variables: Patch the asking run's agent variables, by its run pass. No OpenAPI security entry; the request contract still applies.

Access and drafts

GET /grants: The grants the caller may see. Requires route admission.
POST /grants: Pass on part of a grant. Requires route admission.
POST /grants/agent-roots: Record the administrator's roots for giving people and agents access. Requires route admission.
POST /grants/bindings: A Lys-judged grant binding for a pass a registry issued. Requires route admission.
GET /grants/cannot-give: What the caller cannot pass on. Requires route admission.
POST /grants/changes: The grant changes after a consumer's cursor, with watermarks, readiness and resets. Requires route admission.
POST /grants/check: Check, and record, an exercise. Requires route admission.
POST /grants/check/batch: Any number of checks, answered in order at one revision. Requires route admission.
POST /grants/checkpoint/reset: Discard the refused grant checkpoint the administrator names and rebuild the grants from their log. Requires route admission.
POST /grants/membership: Whether a subject may read or post in a placed channel, at one revision. Requires route admission.
POST /grants/membership/admission: Whether a subject holds a current grant within a workspace. Requires route admission.
GET /grants/membership/counts: The membership capability's work counts and retained entries. Requires route admission.
POST /grants/membership/recipients: The subjects who may read or post in a channel, a bounded page at a time. Requires route admission.
POST /grants/membership/resources: The resources a subject may read or post in, a bounded page at a time. Requires route admission.
GET /grants/model: Lys's own permission model. Requires route admission.
POST /grants/reach: Who may act on each of many resources. Requires route admission.
POST /grants/roots: Issue a root grant, outright or held by draft or by two. Requires route admission.
POST /grants/which: The ids of a kind a subject may act on, by page. Requires route admission.
POST /grants/who: Who may act on a resource. Requires route admission.
POST /grants/why: Why the caller may act. Requires route admission.
GET /grants/{id}: One grant the caller may see. Requires route admission.
POST /grants/{id}/revoke: Revoke a grant and all it derives. Requires route admission.
POST /grants/{id}/tokens: Issue a credential for one grant. Requires route admission.
POST /grants/{id}/tokens/{token_id}/revoke: Revoke one grant credential. Requires route admission.
GET /resources: The resources grants are on. Requires route admission.
GET /requests: The access requests. Requires route admission.
POST /requests: Ask for access. Requires route admission.
POST /requests/{id}/approve: Approve an access request. Requires route admission.
POST /requests/{id}/decline: Decline an access request. Requires route admission.
POST /requests/{id}/reconcile: Settle an approval. Requires route admission.
GET /reviews: The grants due for review. Requires route admission.
POST /reviews/{grant}/keep: Keep a grant under review. Requires route admission.
GET /roles: Every role. Requires route admission.
POST /roles: Make a role. Requires route admission.
GET /roles/{id}: One role. Requires route admission.
POST /roles/{id}/holders: Assign a role. Requires route admission.
POST /roles/{id}/holders/{holder}/end: End a holding. Requires route admission.
POST /roles/{id}/holders/{holder}/move: Move a holding. Requires route admission.
POST /roles/{id}/versions: Revise a role. Requires route admission.
GET /drafts: The drafts the signed-in person may decide. Requires route admission.
POST /drafts: Record an agent's immutable draft. Requires route admission.
POST /drafts/{id}/approve: Record approval without applying the action. Requires route admission.
POST /drafts/{id}/correct: Refuse and save the responsible person's correction. Requires route admission.
POST /drafts/{id}/refuse: Refuse one immutable draft. Requires route admission.
GET /product-drafts: The drafts a person may see; an app's approved drafts, for its connector. Requires route admission.
POST /product-drafts: Record a product's held act as a draft. Requires route admission.
POST /product-drafts/{id}/approve: Approve a product draft. Requires route admission.
POST /product-drafts/{id}/executed: Close an approved draft as executed. Requires route admission.
POST /product-drafts/{id}/refuse: Refuse a product draft. Requires route admission.
POST /product-drafts/{id}/refused-on-execution: Close an approved draft as refused on execution. Requires route admission.

GET /.well-known/oauth-authorization-server: How a connected app is authorized. No OpenAPI security entry; the request contract still applies.
GET /.well-known/oauth-protected-resource: Where the MCP door's authorization is found. No OpenAPI security entry; the request contract still applies.
GET /.well-known/oauth-protected-resource/api/mcp: Where the MCP door's authorization is found, by its screens address. No OpenAPI security entry; the request contract still applies.
GET /.well-known/oauth-protected-resource/mcp: Where the MCP door's authorization is found, by its address. No OpenAPI security entry; the request contract still applies.
GET /.well-known/openid-configuration: The issuer's discovery document. No OpenAPI security entry; the request contract still applies.
GET /apps: Every app the caller may see. Requires route admission.
POST /apps: Register an app: pending until the administrator approves it. Requires route admission.
POST /apps/bench: Open a test bench on a draft schema. Requires route admission.
POST /apps/bench/{id}/ask: Ask the bench: may X do Y to Z. Requires route admission.
POST /apps/bench/{id}/close: Close a bench. Requires route admission.
GET /apps/me: The app a credential signs in as. Requires route admission.
POST /apps/registrars: Make a service account a registrar. Requires route admission.
GET /apps/{app}: One app the caller may see. Requires route admission.
POST /apps/{app}/approve: Approve an app with its sign-in settings, after configured broker credential custody. Requires route admission.
POST /apps/{app}/bearer/issue: Issue or rotate an approved app's bearer, answered once. Requires route admission.
POST /apps/{app}/connector: Give an app approved before connectors its connector, answering to the administrator acting. Requires route admission.
POST /apps/{app}/credentials/issue: Issue an approved app a client credential, answered once. Requires route admission.
POST /apps/{app}/credentials/{credential}/revoke: Revoke one of an app's client credentials. Requires route admission.
POST /apps/{app}/decline: Decline an app. Requires route admission.
POST /apps/{app}/placements: Place a resource in its parent. Requires route admission.
POST /apps/{app}/retire: Retire an app. Requires route admission.
GET /apps/{app}/schema: A schema version, the current one unless `version` names one. Requires route admission.
PUT /apps/{app}/schema: Change a schema, replacing the version named. Requires route admission.
POST /apps/{app}/schema/approve: Approve the schema change waiting. Requires route admission.
POST /apps/{app}/schema/check: What a schema change would do, writing nothing. Requires route admission.
POST /apps/{app}/schema/decline: Decline the schema change waiting. Requires route admission.
POST /apps/{app}/sign_in: Set an approved app's return addresses and whether it is given the person's name. Requires route admission.
GET /connections: What the service is connected to. Requires route admission.
GET /oauth/authorize: Begin an authorization. No OpenAPI security entry; the request contract still applies.
GET /oauth/jwks: The issuer's signing keys. No OpenAPI security entry; the request contract still applies.
POST /oauth/jwks/rotate: Rotate the key passes are signed with; the old key stays published one lifetime. Requires route admission.
GET /oauth/mcp/authorize: Ask the person to connect an app. No OpenAPI security entry; the request contract still applies.
POST /oauth/mcp/consent: The person connects an app or refuses it. No OpenAPI security entry; the request contract still applies.
POST /oauth/mcp/register: An app registers to connect to the MCP door. No OpenAPI security entry; the request contract still applies.
POST /oauth/mcp/token: Exchange a connected app's code or refresh token for tokens. No OpenAPI security entry; the request contract still applies.
POST /oauth/token: Exchange a code or a refresh token for a pass. No OpenAPI security entry; the request contract still applies.
GET /oauth/userinfo: The signed-in subject's claims. Requires route admission.
GET /login: Redirect to the sign-in screen. No OpenAPI security entry; the request contract still applies.
GET /callback: Finish a sign-in and begin a session. No OpenAPI security entry; the request contract still applies.
POST /sign-in: Sign in with a password. No OpenAPI security entry; the request contract still applies.
GET /sign-in/providers: The providers the sign-in page offers. No OpenAPI security entry; the request contract still applies.
GET /sign-in/providers/{id}: Begin sign-in through a provider. No OpenAPI security entry; the request contract still applies.
GET /sign-in-providers: The sign-in providers. Requires route admission.
POST /sign-in-providers: Set a sign-in provider. Requires route admission.

Execution and scheduling

POST /budgets/person/{id}/confirm: Confirm a legacy personal budget. Requires route admission.
GET /budgets/{kind}/{id}: A holder's limits and measured usage. Requires route admission.
PUT /budgets/{kind}/{id}: Replace a holder's limit collection. Requires route admission.
POST /goals/{goal}/active: Suspend or resume a standing aim. Requires route admission.
POST /goals/{goal}/mark: Judge a goal. Requires route admission.
POST /goals/{goal}/resend: A distinct authorised occurrence naming possible prior delivery. Requires route admission.
GET /goals/{goal}/resends/{prior}: The kept resend of one uncertain goal delivery. Requires route admission.
POST /goals/{goal}/words: Reword a standing aim. Requires route admission.
POST /launch-records/{id}/start-again: Start a launch again. Requires route admission.
GET /launch-records/{id}/state: A launch's state. Requires route admission.
POST /launch-records/{id}/withdraw: Withdraw a launch. Requires route admission.
GET /network: The machines. Requires route admission.
GET /network/machine-identities: The computers that joined, as machine identities, and the grants each holds. Requires route admission.
POST /network/machines: Name a machine. Requires route admission.
POST /network/machines/{id}/agents: Allow or remove one agent on a computer. Requires route admission.
POST /network/machines/{id}/folders: The folders inside one folder of a computer. Requires route admission.
POST /network/machines/{id}/join-code: Give a one-time connection code for another computer. Requires route admission.
POST /network/machines/{id}/retire: Retire a machine. Requires route admission.
GET /network/machines/{id}/runner: A machine's runner. Requires route admission.
POST /network/machines/{id}/runner: Name a machine's runner. Requires route admission.
POST /network/machines/{id}/team: Assign or clear a computer's owning team. Requires route admission.
GET /runner-receipts/{index}: A runner act's receipt. No OpenAPI security entry; the request contract still applies.
POST /runner/dial/{machine}/next: A dialled runner's next request. No OpenAPI security entry; the request contract still applies.
POST /runner/dial/{machine}/pass: A joined machine's pass to an app, asked with its join's key. No OpenAPI security entry; the request contract still applies.
POST /runner/dial/{machine}/replies/{ticket}: A dialled runner's reply. No OpenAPI security entry; the request contract still applies.
POST /runner/join: Join another computer's runner with its connection code. No OpenAPI security entry; the request contract still applies.
GET /runner/protocol: The runner protocol. No OpenAPI security entry; the request contract still applies.
GET /runtime/found: The sessions found. Requires route admission.
POST /runtime/found/{session}/reports: Report a found session. Requires route admission.
GET /runtime/live: The sessions still running. Requires route admission.
GET /runtime/message-edges: Caller-visible message addresses from the message service, mapped to Lys identities. Requires route admission.
GET /runtime/sessions: Every runtime session. Requires route admission.
POST /runtime/sessions/{id}/compact: Compact a session. Requires route admission.
POST /runtime/sessions/{id}/end: End a session. Requires route admission.
POST /runtime/sessions/{id}/input: Type into a session. Requires route admission.
POST /runtime/sessions/{id}/input-bytes: Write exact bytes to a session. Requires route admission.
POST /runtime/sessions/{id}/keys: Send a session keys. Requires route admission.
POST /runtime/sessions/{id}/read: Read a session's screen. Requires route admission.
POST /runtime/sessions/{id}/read-bytes: Read a session's exact output bytes. Requires route admission.
POST /runtime/sessions/{id}/resize: Resize a session. Requires route admission.
GET /runtime/sessions/{id}/variables: A session's variables. Requires route admission.
POST /runtime/sessions/{id}/variables: Patch a session's variables with the revision read. Requires route admission.
POST /runtime/sessions/{id}/wait: Wait for a session to show a pattern. Requires route admission.
POST /runtime/sessions/{id}/words/{slot}: Set a slot at a session's layer. Requires route admission.
GET /runtime/sessions/{session}/control-receipts: A bounded page of session control evidence. Requires route admission.
POST /runtime/sessions/{session}/control-receipts/{operation}/reconcile: The responsible person's decision about uncertain delivery. Requires route admission.
GET /runtime/sessions/{session}/controls: A session's current control identifiers. Requires route admission.
GET /runtime/stop-everything: Whether everything is stopped, by whom, when and why. Requires route admission.
POST /runtime/stop-everything: Stop every session on every computer and refuse every start. Requires route admission.
POST /runtime/stop-everything/console: Stop every session under the service's own console signature. Requires route admission.
POST /runtime/stop-everything/release: Let agents start again. Requires route admission.
GET /schedules: The schedules the caller may see. Requires route admission.
POST /schedules: Set a schedule. Requires route admission.
GET /schedules/{id}: A schedule with every occurrence and delivery. Requires route admission.
POST /schedules/{id}/change: Pause, resume or edit a schedule, keeping its count. Requires route admission.
POST /schedules/{id}/stop: Stop a schedule. Requires route admission.
GET /seats: Every seat with its state from its runner's own knowledge, and whether the runners were read. Requires route admission.
POST /seats: Add a seat: a name an agent runs under on one machine from one reviewed profile version. Requires route admission.
GET /seats/owned: Every seat owner each runner started, live and unreachable as the runner proved them at the kernel. Requires route admission.
GET /seats/unregistered: The sessions runners hold for no seat. Requires route admission.
GET /seats/{name}: One seat with its state. Requires route admission.
POST /seats/{name}/attach: Read a seat's live session as lines, following it. Requires route admission.
GET /seats/{name}/import: A seat's imports, its selected import and its latest dry run. Requires route admission.
POST /seats/{name}/import/confirm: Confirm one seat's exact dry-run plan and apply it, resumably, under one operation. Requires route admission.
POST /seats/{name}/import/dry-run: Read one seat's declared sources at one instant and show the whole import plan; nothing is sent, started or changed. Requires route admission.
POST /seats/{name}/restart: Stop a seat and start it again under a new session. Requires route admission.
POST /seats/{name}/retire: Retire a stopped seat and release its name without discarding its history. Requires route admission.
POST /seats/{name}/send: Send a seat a message, delivered as a user turn. Requires route admission.
POST /seats/{name}/start: Start a seat, managed, through the server's own start path. Requires route admission.
POST /seats/{name}/stop: Stop a seat between turns, or mid-turn with force. Requires route admission.
POST /seats/{name}/type: A line typed in an attach, delivered as a user turn. Requires route admission.
POST /seats/{name}/version: Select a reviewed profile version for a stopped seat. Requires route admission.
GET /sessions: The caller's sessions. Requires route admission.
POST /sessions/{id}/end: End one's own session. Requires route admission.

Organisation and settings

GET /canvas: The caller's canvas: their arrangement and saved layouts. Requires route admission.
PUT /canvas: Keep the caller's arrangement. Requires route admission.
POST /canvas/layouts: Save an arrangement as a layout of the caller's, by name. Requires route admission.
POST /canvas/layouts/remove: Remove a layout of the caller's, by name. Requires route admission.
GET /configuration: The service's configuration. Requires route admission.
PUT /configuration: Set the organisation zone at its current version. Requires route admission.
GET /harnesses: The programmes Lys describes and their reviewed builds. Requires route admission.
GET /harnesses/plugins: The Claude Code plugins installed in one config folder of a computer, as its runner reads them. Requires route admission.
GET /skills: The skills Lys keeps. Requires route admission.
POST /skills: Keep a skill's text. Requires route admission.
GET /teams: Every team. Requires route admission.
POST /teams: Create a team. Requires route admission.
GET /teams/{id}: One team. Requires route admission.
GET /teams/{id}/budget: A team's limits and measured usage. Requires route admission.
PUT /teams/{id}/budget: Replace a team's limit collection. Requires route admission.
GET /teams/{id}/goals: A team's goals. Requires route admission.
POST /teams/{id}/goals: Set a goal on a team. Requires route admission.
POST /teams/{id}/members: Add a team member. Requires route admission.
POST /teams/{id}/members/{member}/confirm: Confirm a held membership. Requires route admission.
POST /teams/{id}/members/{member}/remove: Remove a member. Requires route admission.
POST /teams/{id}/nesting: Replace a team parent and lead. Requires route admission.
POST /teams/{id}/retire: Retire a team. Requires route admission.
GET /tree: The caller's owned and led teams and descendants. Requires route admission.
GET /words: The words a seat is sent: every layer and template as held. Requires route admission.
POST /words/preview: Render a slot for a session or an agent; nothing is sent. Requires route admission.
POST /words/templates/{name}: Save a named template. Requires route admission.
POST /words/{slot}: Set a slot at the workspace layer. Requires route admission.
GET /secrets: The secrets. Requires route admission.
POST /secrets/add: Add a secret with its value. Requires route admission.
GET /secrets/audit: The secrets' audit. Requires route admission.
POST /secrets/drop: Drop a secret handle. Requires route admission.
GET /secrets/grants: The secrets' grants. Requires route admission.
GET /secrets/handles: The secret handles. Requires route admission.
POST /secrets/recipients: A secret's recipients. Requires route admission.
POST /secrets/replace: Change a secret's value. Requires route admission.
POST /secrets/retire: Retire a secret. Requires route admission.
GET /secrets/revocation: The secrets' revocations. Requires route admission.
POST /secrets/scope: Scope a secret. Requires route admission.
GET /secrets/settings: The secrets' settings. Requires route admission.

Service and evidence

GET /authority: The authority this service speaks for. No OpenAPI security entry; the request contract still applies.
GET /changes: Wait for the next change signal. Requires route admission.
GET /dashboard: The caller's own agents, how each is going, and what waits on the caller. Requires route admission.
GET /health: That this service is serving, with its name and build. No OpenAPI security entry; the request contract still applies.
POST /link-audit: Deliver a link-audit record. Requires route admission.
POST /link-audit/person: Look up a link-audit holder. Requires route admission.
GET /mcp: MCP server stream availability. Requires route admission.
POST /mcp: MCP calls through the admitted HTTP router. Requires route admission.
GET /openapi.json: This document. No OpenAPI security entry; the request contract still applies.
GET /receipts/{index}: A directory receipt, publicly. No OpenAPI security entry; the request contract still applies.
GET /service-accounts: The service accounts. Requires route admission.
POST /service-accounts: Create a service account. Requires route admission.
POST /service-accounts/{id}/retire: Retire a service account. Requires route admission.
GET /service-key: The service's public key. No OpenAPI security entry; the request contract still applies.
POST /setup: Finish the administrator's first-run setup. Requires route admission.
POST /setup/administrator: Register the first administrator. No OpenAPI security entry; the request contract still applies.
POST /setup/open: Open first-run setup with its code. No OpenAPI security entry; the request contract still applies.
POST /setup/password: Set the first administrator's password. No OpenAPI security entry; the request contract still applies.
GET /surface-contract: The surface registration and computer admission contract. No OpenAPI security entry; the request contract still applies.

Access and refusals explains admission failures. MCP reaches these contracts through the agent’s admitted connection.