{"openapi":"3.1.0","info":{"title":"Sno.ai agent API","version":"1.0.0","description":"Agent-facing HTTP endpoints. Read /auth.md for account access."},"servers":[{"url":"https://www.sno.ai"}],"components":{"securitySchemes":{"accountBearer":{"type":"http","scheme":"bearer","description":"Account access token obtained through the flow at /auth.md."},"machineBearer":{"type":"http","scheme":"bearer","description":"This computer's registered machine secret."},"sessionCookie":{"type":"apiKey","in":"cookie","name":"__Secure-better-auth.session_token","description":"Signed-in browser session; local HTTP uses better-auth.session_token."},"preClaimBearer":{"type":"http","scheme":"bearer","description":"Unclaimed agent credential with sno.events scope; events are held without machine attribution."}},"schemas":{"AgentClaim":{"type":"object","properties":{"user_code":{"type":"string","pattern":"^\\d{6}$"},"expires_in":{"type":"number","enum":[1800]},"verification_uri":{"type":"string","format":"uri"},"interval":{"type":"number","enum":[5]}},"required":["user_code","expires_in","verification_uri","interval"],"description":"The person confirms using the link and 6-digit code."},"UsageBar":{"type":"object","properties":{"plan":{"type":"string","enum":["FREE","PLUS","PRO","MAX"]},"memory":{"type":"object","properties":{"percent_left":{"type":"number","minimum":0,"maximum":100},"reset_at":{"type":"string","format":"date-time"}},"required":["percent_left","reset_at"]},"retrospective":{"type":"object","properties":{"percent_left":{"type":"number","minimum":0,"maximum":100},"reset_at":{"type":"string","format":"date-time"}},"required":["percent_left","reset_at"]},"balance_cents":{"type":"integer"},"top_up_url":{"type":"string"}},"required":["plan","memory","retrospective","balance_cents","top_up_url"],"description":"Remaining allowance percentages, reset times and purchased balance in US cents."},"AccountComputers":{"type":"object","properties":{"computers":{"type":"array","items":{"type":"object","properties":{"machine_uuid":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"first_seen_at":{"type":"string","format":"date-time"},"last_seen_at":{"type":"string","format":"date-time"},"via":{"type":"string","enum":["attached"]}},"required":["machine_uuid","first_seen_at","last_seen_at","via"]}}},"required":["computers"]},"SnoEvent":{"type":"object","properties":{"schema_version":{"type":"string","enum":["v1"]},"event_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"event_type":{"type":"string","description":"Registered event type; its payload and lane must match the event registry."},"lane":{"type":"string","enum":["memory","llm","skill","security","squad","rsi"]},"ts_edge_ms":{"type":"integer"},"consent_level":{"type":"string","enum":["off","metadata-only","full"]},"redacted":{"type":"boolean"},"chain_epoch":{"type":"integer","minimum":0},"seq":{"type":"integer","minimum":0},"scope":{"type":"object","properties":{"user_id":{"type":"string","description":"CUID2 identity."},"machine_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"user_account_id":{"type":"string","description":"CUID2 identity."},"agent_id":{"type":"string","enum":["openclaw","hermes","claude-code","codex","pi","cursor","sno-cli","sno-control-plane"]},"project_id":{"type":"string","minLength":1},"session_uuid":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"required":["user_id","machine_id","agent_id"],"additionalProperties":false},"hash_chain":{"type":"object","properties":{"prev":{"anyOf":[{"type":"string","enum":["GENESIS"]},{"type":"string","pattern":"^[a-f0-9]{64}$"}]},"self":{"type":"string","pattern":"^[a-f0-9]{64}$"}},"required":["prev","self"],"additionalProperties":false},"payload":{"type":"object","additionalProperties":{},"description":"Event-specific fields validated by EventPayloadSchemas in lib/observability/event-envelope.ts; payload refinements and hash-chain calculation are not represented in this document."}},"required":["schema_version","event_id","event_type","lane","ts_edge_ms","consent_level","redacted","chain_epoch","seq","scope","hash_chain","payload"],"additionalProperties":false,"description":"One event envelope, never an array or batch wrapper. Machine identity and the existing event/hash rules determine whether it can be forwarded; otherwise it is held."}},"parameters":{}},"paths":{"/api/v1/agent-auth/identity":{"post":{"summary":"Register an agent anonymously or for a person's email","requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["anonymous"]}},"required":["type"]},{"type":"object","properties":{"type":{"type":"string","enum":["service_auth"]},"login_hint":{"type":"string","format":"email"}},"required":["type","login_hint"]}]}}}},"responses":{"200":{"description":"Registration and either a confirmation ceremony or an anonymous assertion.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"registration_id":{"type":"string"},"claim_token":{"type":"string"},"post_claim_scopes":{"type":"array","items":{"type":"string","enum":["sno.account"]}},"registration_type":{"type":"string","enum":["service_auth"]},"claim":{"$ref":"#/components/schemas/AgentClaim"}},"required":["registration_id","claim_token","post_claim_scopes","registration_type","claim"]},{"type":"object","properties":{"registration_id":{"type":"string"},"claim_token":{"type":"string"},"post_claim_scopes":{"type":"array","items":{"type":"string","enum":["sno.account"]}},"registration_type":{"type":"string","enum":["anonymous"]},"identity_assertion":{"type":"string"},"pre_claim_scopes":{"type":"array","items":{"type":"string","enum":["sno.events"]}},"claim_token_expires":{"type":"string","format":"date-time"}},"required":["registration_id","claim_token","post_claim_scopes","registration_type","identity_assertion","pre_claim_scopes","claim_token_expires"]}]}}}},"400":{"description":"invalid_request or unsupported_identity_type.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/agent-auth/claim":{"post":{"summary":"Start a confirmation ceremony for an existing registration","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"claim_token":{"type":"string","minLength":1},"email":{"type":"string","format":"email"}},"required":["claim_token"]}}}},"responses":{"200":{"description":"New confirmation link and code.","content":{"application/json":{"schema":{"type":"object","properties":{"claim":{"$ref":"#/components/schemas/AgentClaim"}},"required":["claim"]}}}},"400":{"description":"invalid_request or expired_token.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"403":{"description":"email_mismatch: service-auth email must match the registration.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/agent-auth/claim/complete":{"post":{"summary":"Complete confirmation in the signed-in person's browser","security":[{"accountBearer":[]},{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"claim_attempt_token":{"type":"string","minLength":1},"user_code":{"type":"string","pattern":"^\\d{6}$"}},"required":["claim_attempt_token","user_code"]}}}},"responses":{"200":{"description":"Registration claimed.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"invalid_request, expired_token or wrong_code.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"403":{"description":"email_mismatch.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/agent-auth/token":{"post":{"summary":"Exchange a claim token or identity assertion for an access token","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"anyOf":[{"type":"object","properties":{"grant_type":{"type":"string","enum":["urn:workos:agent-auth:grant-type:claim"]},"claim_token":{"type":"string","minLength":1},"assertion":{"type":"string"}},"required":["grant_type","claim_token"]},{"type":"object","properties":{"grant_type":{"type":"string","enum":["urn:ietf:params:oauth:grant-type:jwt-bearer"]},"assertion":{"type":"string","minLength":1},"claim_token":{"type":"string"}},"required":["grant_type","assertion"]}]}}}},"responses":{"200":{"description":"Anonymous event access or a renewable account session.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"number"},"scope":{"type":"string","enum":["sno.events"]}},"required":["access_token","token_type","expires_in","scope"]},{"type":"object","properties":{"access_token":{"type":"string"},"token_type":{"type":"string","enum":["Bearer"]},"expires_in":{"type":"number"},"scope":{"type":"string","enum":["sno.account"]},"identity_assertion":{"type":"string"},"assertion_expires":{"type":"string","format":"date-time"}},"required":["access_token","token_type","expires_in","scope","identity_assertion","assertion_expires"]}]}}}},"400":{"description":"invalid_request, unsupported_grant_type, invalid_grant, expired_token or authorization_pending; poll at the claim interval.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/agent-auth/revoke":{"post":{"summary":"Revoke an access token; the registration assertion remains usable","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"token":{"type":"string"},"token_type_hint":{"type":"string"}}}}}},"responses":{"200":{"description":"Returns an empty object even when the token is absent or already revoked.","content":{"application/json":{"schema":{"type":"object","properties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/account/summary":{"get":{"summary":"Read the signed-in account, usage, computers and agents","security":[{"accountBearer":[]},{"sessionCookie":[]}],"responses":{"200":{"description":"Failed sections are omitted and recorded in errors; ignore unknown section names and fields.","content":{"application/json":{"schema":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"generated_at":{"type":"string","format":"date-time"},"sections":{"type":"object","properties":{"account":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":["string","null"]},"name":{"type":["string","null"]}},"required":["id","email","name"]},"plan_and_usage":{"$ref":"#/components/schemas/UsageBar"},"computers":{"$ref":"#/components/schemas/AccountComputers"},"agents":{"type":"object","properties":{"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string","enum":["anonymous","service_auth"]},"status":{"type":"string","enum":["claimed"]},"createdAt":{"type":"string","format":"date-time"},"lastTokenAt":{"type":["string","null"],"format":"date-time"},"ipAddress":{"type":["string","null"]},"revokedAt":{"type":["string","null"],"format":"date-time"}},"required":["id","type","status","createdAt","lastTokenAt","ipAddress","revokedAt"]}}},"required":["agents"]}},"additionalProperties":{"type":"object","properties":{},"additionalProperties":{}}},"errors":{"type":"object","additionalProperties":{"type":"string"}}},"required":["version","generated_at","sections","errors"]}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"404":{"description":"user_not_found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/account/computers":{"get":{"summary":"List computers attached to the account, newest first","security":[{"accountBearer":[]},{"sessionCookie":[]}],"responses":{"200":{"description":"Account computers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountComputers"}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/usage/bar":{"get":{"summary":"Read remaining Sno allowance and purchased balance","security":[{"machineBearer":[]},{"accountBearer":[]},{"sessionCookie":[]}],"responses":{"200":{"description":"Current usage bar.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageBar"}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/activity":{"get":{"summary":"Read activity for the authenticated account or computer","description":"The statistics service's body and status are passed through, including non-JSON responses. On an object-shaped first page, held events are added as unclassified and unclassified_truncated. Cursors are opaque and limited to 1024 UTF-8 bytes.","security":[{"machineBearer":[]},{"accountBearer":[]},{"sessionCookie":[]}],"parameters":[{"schema":{"type":"string","description":"Integer from 1 to 500; default 100."},"required":false,"description":"Integer from 1 to 500; default 100.","name":"limit","in":"query"},{"schema":{"type":"string"},"required":false,"name":"cursor","in":"query"},{"schema":{"type":"string"},"required":false,"name":"since","in":"query"},{"schema":{"type":"string","enum":["memory","llm","skill","security","squad","rsi"]},"required":false,"name":"lane","in":"query"}],"responses":{"200":{"description":"Activity response passed through from the statistics service.","content":{"application/json":{"schema":{"description":"Statistics-service response. First-page objects also include unclassified: [{event_id,event_type,agent_id,machine_uuid,reason,received_at}] and unclassified_truncated: boolean."}}}},"400":{"description":"invalid_limit, cursor_too_long or lane_not_in_enum.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}},"default":{"description":"Upstream status, Content-Type and body are passed through unchanged."}}}},"/api/v1/consent":{"get":{"summary":"Read consent for a computer or all computers of the account","security":[{"machineBearer":[]},{"accountBearer":[]},{"sessionCookie":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"required":false,"name":"machine_uuid","in":"query"},{"schema":{"type":"string","enum":["memory","llm","skill","security","squad","rsi"],"description":"Defaults to memory."},"required":false,"description":"Defaults to memory.","name":"lane","in":"query"}],"responses":{"200":{"description":"One effective level for a machine, or all owned scoped levels for a session without machine_uuid.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"level":{"type":"string","enum":["off","metadata-only","full"]}},"required":["level"]},{"type":"object","properties":{"levels":{"type":"array","items":{"type":"object","properties":{"user_cuid":{"type":"string","description":"CUID2 identity."},"machine_uuid":{"type":["string","null"],"pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"level":{"type":"string","enum":["off","metadata-only","full"]}},"required":["user_cuid","machine_uuid","level"]}}},"required":["levels"]}]}}}},"400":{"description":"invalid_request, lane_not_in_enum or machine_uuid_mismatch.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"403":{"description":"machine_not_owned.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"409":{"description":"no_linked_cuid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}},"post":{"summary":"Set consent for the authenticated computer or account","description":"Without machine_uuid, a session writes the baseline for every linked identity. Omitting lane sets the all-lane baseline.","security":[{"machineBearer":[]},{"accountBearer":[]},{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"level":{"type":"string","enum":["off","metadata-only","full"]},"reason":{"type":"string","maxLength":256},"machine_uuid":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"lane":{"type":"string","enum":["memory","llm","skill","security","squad","rsi"]}},"required":["level"],"additionalProperties":false}}}},"responses":{"200":{"description":"Consent level and number of changed rows.","content":{"application/json":{"schema":{"type":"object","properties":{"level":{"type":"string","enum":["off","metadata-only","full"]},"written":{"type":"integer","minimum":0}},"required":["level","written"]}}}},"400":{"description":"invalid_request, lane_not_in_enum or machine_uuid_mismatch.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"403":{"description":"machine_not_owned.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"409":{"description":"no_linked_cuid.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}},"502":{"description":"Consent rows were written, but forwarding their audit events failed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["consent_audit_forward_failed"]},"written":{"type":"integer"}},"required":["error","written"]}}}}}}},"/api/v1/events":{"post":{"summary":"Receive a single event and forward it or retain it as held","security":[{"machineBearer":[]},{"accountBearer":[]},{"sessionCookie":[]},{"preClaimBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SnoEvent"}}}},"responses":{"202":{"description":"Forwarded receipt, or held event and the reason it could not be forwarded as sent.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"receipt_id":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"required":["receipt_id"]},{"type":"object","properties":{"held":{"type":"boolean","enum":[true]},"warning":{"type":"string"}},"required":["held","warning"]}]}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"409":{"description":"Statistics-service chain-position response, passed through for resend."},"422":{"description":"Statistics-service chain-position response, passed through for resend."},"424":{"description":"Dependency or body-read failure. Upstream failures may instead preserve the upstream Content-Type and body.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}},"429":{"description":"Upstream rate limit; preserves the upstream body and Retry-After header."}}}},"/api/v1/audit/verify":{"get":{"summary":"Retrieve an event's audit proof within the caller's scope","security":[{"machineBearer":[]},{"accountBearer":[]},{"sessionCookie":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"},"required":true,"name":"event_id","in":"query"}],"responses":{"200":{"description":"Upstream audit proof, passed through unchanged.","content":{"application/json":{"schema":{"description":"Audit proof response from the statistics service; the route does not define or transform its shape."}}}},"400":{"description":"missing_event_id or invalid_event_id.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}},"default":{"description":"Upstream status, Content-Type and body are passed through unchanged."}}}},"/api/v1/device/code":{"post":{"summary":"Start attaching this registered computer to an account","security":[{"machineBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_cuid":{"type":"string","description":"CUID2 identity."},"machine_uuid":{"type":"string","pattern":"^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"}},"required":["user_cuid","machine_uuid"]}}}},"responses":{"200":{"description":"Device code and the person's verification link and code.","content":{"application/json":{"schema":{"type":"object","properties":{"device_code":{"type":"string"},"user_code":{"type":"string"},"verification_uri":{"type":"string"},"verification_uri_complete":{"type":"string"},"interval":{"type":"number","enum":[5]},"expires_in":{"type":"number","enum":[1800]}},"required":["device_code","user_code","verification_uri","verification_uri_complete","interval","expires_in"]}}}},"400":{"description":"invalid_json or invalid_request (with Zod issues).","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"403":{"description":"machine_mismatch: supplied identities must match the machine credential.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/device/approve":{"post":{"summary":"Approve a computer connection as the signed-in person","security":[{"accountBearer":[]},{"sessionCookie":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user_code":{"type":"string","minLength":1}},"required":["user_code"]}}}},"responses":{"200":{"description":"Computer attached to the account.","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]}},"required":["ok"]}}}},"400":{"description":"invalid_request.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"401":{"description":"A valid credential is required: unauthorized or machine_unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"409":{"description":"machine_not_registered, cuid_already_claimed, person_bound_to_other_account or machine_already_claimed.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"410":{"description":"code_consumed: code is no longer pending or has expired.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"],"additionalProperties":{}}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/device/token":{"post":{"summary":"Poll whether a computer has been attached","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"device_code":{"type":"string","minLength":1},"grant_type":{"type":"string","enum":["urn:ietf:params:oauth:grant-type:device_code"]}},"required":["device_code","grant_type"]}}}},"responses":{"200":{"description":"Computer claimed; this endpoint does not issue an access token.","content":{"application/json":{"schema":{"type":"object","properties":{"user_account_id":{"type":"string"},"status":{"type":"string","enum":["claimed"]}},"required":["user_account_id","status"]}}}},"400":{"description":"Pending, expired or denied. slow_down includes the new polling interval in seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["invalid_request","expired_token","access_denied","authorization_pending","slow_down"]},"interval":{"type":"integer"}},"required":["error"]}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/a2a":{"post":{"summary":"Read Sno's fixed guide through A2A SendMessage","description":"SendMessage returns llms.txt and links to llms-full.txt and auth.md. Parameters do not affect the answer. Other methods, including message/send, and invalid bodies return JSON-RPC error -32601 with HTTP 200.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"method":{"type":"string"},"params":{}},"additionalProperties":{}}}}},"responses":{"200":{"description":"A2A message or JSON-RPC method-not-found error; missing id is returned as null.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"result":{"type":"object","properties":{"message":{"type":"object","properties":{"messageId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["ROLE_AGENT"]},"parts":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"}},"required":["text"]}}},"required":["messageId","role","parts"]}},"required":["message"]}},"required":["jsonrpc","id","result"]},{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"error":{"type":"object","properties":{"code":{"type":"number","enum":[-32601]},"message":{"type":"string","enum":["Method not found"]}},"required":["code","message"]}},"required":["jsonrpc","id","error"]}]}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}},"/api/v1/mcp":{"post":{"summary":"Read Sno's fixed guide through an MCP tool","description":"MCP Streamable HTTP (2025-06-18) without sessions: initialize, ping, tools/list and tools/call about_sno, which returns llms.txt and links to llms-full.txt and auth.md. A notification returns 202 with no body; other methods return JSON-RPC error -32601 and an unknown tool -32602, both with HTTP 200; an unparseable body returns -32700 with HTTP 400.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"anyOf":[{"type":"string"},{"type":"number"}]},"method":{"type":"string"},"params":{}},"additionalProperties":{}}}}},"responses":{"200":{"description":"JSON-RPC result or error.","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"null"}]},"result":{},"error":{"type":"object","properties":{"code":{"type":"number"},"message":{"type":"string"}},"required":["code","message"]}},"required":["jsonrpc","id"]}}}},"202":{"description":"Notification accepted; no body."},"400":{"description":"Body is not JSON.","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"type":"null"},"error":{"type":"object","properties":{"code":{"type":"number","enum":[-32700]},"message":{"type":"string"}},"required":["code","message"]}},"required":["jsonrpc","id","error"]}}}},"424":{"description":"The operation could not complete; retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","enum":["temporarily_unavailable"]},"retryable":{"type":"boolean","enum":[true]}},"required":["error","retryable"]}}}}}}}},"webhooks":{}}