{"openapi":"3.1.0","info":{"title":"Audon API","version":"1.0.0","description":"Every capability of the Audon product. The same operations are available as MCP tools at /mcp. Money fields are strings of exact integer micros (10⁻⁶ of the currency) plus amount_minor and amount_decimal.","contact":{"name":"Audon Software LLC"}},"servers":[{"url":"https://audon.ai"}],"paths":{"/v1/organizations":{"post":{"operationId":"organizations.create","summary":"Create organization","description":"Create a new organization. The calling user becomes its owner. Set demo=true for a clearly labeled synthetic-data sandbox.\n\nMCP tool: `organization_create`. UI: `/onboarding`.","tags":["organizations"],"security":[{},{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"country":{"type":"string","enum":["US","GB","AE","SA","OTHER"]},"timezone":{"type":"string","maxLength":64},"demo":{"default":false,"type":"boolean"}},"required":["name"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"organizations.list","summary":"List organizations","description":"List organizations the caller can access. Token-based callers only see the organization their credential belongs to.\n\nMCP tool: `organization_list`. UI: `/app (organization switcher)`.","tags":["organizations"],"security":[{},{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/current":{"get":{"operationId":"organizations.get","summary":"Get organization","description":"Get the active organization, including plan and the caller’s role and effective scopes.\n\nMCP tool: `organization_get`. UI: `/app/settings`.","tags":["organizations"],"security":[{"bearer":["org:read"]}],"x-required-scope":"org:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"organizations.update","summary":"Update organization","description":"Rename the organization or change country, timezone or display currency.\n\nMCP tool: `organization_update`. UI: `/app/settings`.","tags":["organizations"],"security":[{"bearer":["org:write"]}],"x-required-scope":"org:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"country":{"anyOf":[{"type":"string","enum":["US","GB","AE","SA","OTHER"]},{"type":"null"}]},"timezone":{"type":"string","maxLength":64},"display_currency":{"type":"string","enum":["USD","GBP","EUR","AED","SAR"]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"organizations.delete","summary":"Request organization deletion","description":"Schedule deletion of the organization and all its data after a 14-day grace period. Any paid subscription is set to cancel at period end now and is cancelled immediately at the provider when deletion runs. Agents and API keys receive approval_required; a signed-in owner must confirm by typing the organization name.\n\nMCP tool: `organization_delete`. UI: `/app/settings#danger`.","tags":["organizations"],"security":[{"bearer":["org:delete"]}],"x-required-scope":"org:delete","parameters":[{"name":"confirm_name","in":"query","required":false,"schema":{"type":"string"}},{"name":"reason","in":"query","required":false,"schema":{"type":"string","maxLength":500}}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/organizations/current/cancel-deletion":{"post":{"operationId":"organizations.cancel_deletion","summary":"Cancel scheduled deletion","description":"Cancel a scheduled organization deletion during the grace period. Agents and API keys receive approval_required; a signed-in owner must cancel. Owners are emailed when a deletion is cancelled.\n\nMCP tool: `organization_cancel_deletion`. UI: `/app/settings#danger`.","tags":["organizations"],"security":[{"bearer":["org:delete"]}],"x-required-scope":"org:delete","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/members":{"get":{"operationId":"team.list","summary":"List members and invitations","description":"List organization members (with roles) and pending invitations.\n\nMCP tool: `team_list`. UI: `/app/team`.","tags":["team"],"security":[{"bearer":["team:read"]}],"x-required-scope":"team:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/members/invite":{"post":{"operationId":"team.invite","summary":"Invite member","description":"Invite a person by email with a role (admin, analyst, billing_admin, read_only). Only owners can invite owners.\n\nMCP tool: `team_invite`. UI: `/app/team`.","tags":["team"],"security":[{"bearer":["team:write"]}],"x-required-scope":"team:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":200,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"role":{"type":"string","enum":["owner","admin","analyst","billing_admin","read_only"]}},"required":["email","role"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invites/{invite_id}":{"delete":{"operationId":"team.revoke_invite","summary":"Revoke invitation","description":"Revoke a pending invitation.\n\nMCP tool: `team_revoke_invite`. UI: `/app/team`.","tags":["team"],"security":[{"bearer":["team:write"]}],"x-required-scope":"team:write","parameters":[{"name":"invite_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/members/{member_id}":{"patch":{"operationId":"team.update_member","summary":"Change member role","description":"Change a member’s role. Only owners can grant or remove the owner role; the last owner cannot be demoted.\n\nMCP tool: `team_update_member`. UI: `/app/team`.","tags":["team"],"security":[{"bearer":["team:write"]}],"x-required-scope":"team:write","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["owner","admin","analyst","billing_admin","read_only"]}},"required":["role"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"team.remove_member","summary":"Remove member","description":"Remove a member. Their API keys and agent connections for this organization stop working immediately.\n\nMCP tool: `team_remove_member`. UI: `/app/team`.","tags":["team"],"security":[{"bearer":["team:write"]}],"x-required-scope":"team:write","parameters":[{"name":"member_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connectors/catalog":{"get":{"operationId":"connectors.catalog","summary":"List available connectors","description":"List supported providers, the credential each needs, exactly what is read and what is never read.\n\nMCP tool: `connector_list_available`. UI: `/app/integrations`.","tags":["connectors"],"security":[{},{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections":{"post":{"operationId":"connections.create","summary":"Connect provider","description":"Connect an OpenAI or Anthropic organization with an Admin API key, used read-only, or an xAI team with a team-scoped management key. The key is validated, encrypted server-side, and never returned. Use provider \"demo\" only in demo organizations.\n\nMCP tool: `connection_create`. UI: `/app/integrations#connect`.","tags":["connections"],"security":[{"bearer":["connections:write"]}],"x-required-scope":"connections:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","anthropic","xai","demo"]},"label":{"type":"string","minLength":1,"maxLength":80},"admin_api_key":{"type":"string","minLength":8,"maxLength":500}},"required":["provider"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"connections.list","summary":"List connections","description":"List provider connections with health, last sync and capability coverage. Secrets are never included.\n\nMCP tool: `connection_list`. UI: `/app/integrations`.","tags":["connections"],"security":[{"bearer":["connections:read"]}],"x-required-scope":"connections:read","parameters":[{"name":"include_disconnected","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections/{connection_id}":{"get":{"operationId":"connections.get","summary":"Get connection status","description":"Get one connection’s health, last sync time, last error and capabilities.\n\nMCP tool: `connection_status`. UI: `/app/integrations`.","tags":["connections"],"security":[{"bearer":["connections:read"]}],"x-required-scope":"connections:read","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"connections.disconnect","summary":"Disconnect provider","description":"Disconnect a provider: the encrypted credential is destroyed and future syncs stop. Historical spend is kept per your retention setting unless purge_data=true. Also revoke the key at the provider.\n\nMCP tool: `connection_disconnect`. UI: `/app/integrations`.","tags":["connections"],"security":[{"bearer":["connections:write"]}],"x-required-scope":"connections:write","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"purge_data","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections/{connection_id}/test":{"post":{"operationId":"connections.test","summary":"Test connection","description":"Re-validate the stored credential against the provider with a minimal read-only request.\n\nMCP tool: `connection_test`. UI: `/app/integrations`.","tags":["connections"],"security":[{"bearer":["connections:write"]}],"x-required-scope":"connections:write","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections/{connection_id}/sync":{"post":{"operationId":"connections.sync","summary":"Sync connection now","description":"Queue a background re-import of recent cost and usage data (default last 7 days). Returns a job id; data appears in spend endpoints when done.\n\nMCP tool: `connection_sync`. UI: `/app/integrations`.","tags":["connections"],"security":[{"bearer":["connections:write"]}],"x-required-scope":"connections:write","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"days":{"default":7,"type":"integer","minimum":1,"maximum":90}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/connections/{connection_id}/rotate":{"post":{"operationId":"connections.rotate","summary":"Rotate credential","description":"Replace the stored Admin API key with a new one. The new key is validated first; the old ciphertext is destroyed.\n\nMCP tool: `connection_rotate`. UI: `/app/integrations`.","tags":["connections"],"security":[{"bearer":["connections:write"]}],"x-required-scope":"connections:write","parameters":[{"name":"connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"admin_api_key":{"type":"string","minLength":8,"maxLength":500}},"required":["admin_api_key"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audits":{"post":{"operationId":"audits.create","summary":"Start audit","description":"Start a read-only historical spend audit over the last N days (default 30) for all or selected connections. Runs in the background; poll audit_get until status is completed or failed.\n\nMCP tool: `audit_start`. UI: `/app/audits#new`.","tags":["audits"],"security":[{"bearer":["audits:write"]}],"x-required-scope":"audits:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"period_days":{"default":30,"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"connection_ids":{"maxItems":50,"type":"array","items":{"type":"string","pattern":"^con_[0-9a-z]+$"}}},"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"operationId":"audits.list","summary":"List audits","description":"List audits, newest first, with status and observed spend.\n\nMCP tool: `audit_list`. UI: `/app/audits`.","tags":["audits"],"security":[{"bearer":["audits:read"]}],"x-required-scope":"audits:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["queued","syncing","analyzing","completed","failed","cancelled"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audits/{audit_id}":{"get":{"operationId":"audits.get","summary":"Get audit","description":"Get an audit’s status, progress stages, coverage, observed spend and finding counts by classification.\n\nMCP tool: `audit_get`. UI: `/app/audits/{audit_id}`.","tags":["audits"],"security":[{"bearer":["audits:read"]}],"x-required-scope":"audits:read","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audits/{audit_id}/retry":{"post":{"operationId":"audits.retry","summary":"Retry audit","description":"Retry a failed or cancelled audit with the same scope. Does not consume another free audit.\n\nMCP tool: `audit_retry`. UI: `/app/audits/{audit_id}`.","tags":["audits"],"security":[{"bearer":["audits:write"]}],"x-required-scope":"audits:write","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audits/{audit_id}/cancel":{"post":{"operationId":"audits.cancel","summary":"Cancel audit","description":"Cancel a queued or running audit.\n\nMCP tool: `audit_cancel`. UI: `/app/audits/{audit_id}`.","tags":["audits"],"security":[{"bearer":["audits:write"]}],"x-required-scope":"audits:write","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audits/{audit_id}/findings":{"get":{"operationId":"audits.findings","summary":"List audit findings","description":"List the findings produced or refreshed by one audit.\n\nMCP tool: `audit_list_findings`. UI: `/app/audits/{audit_id}`.","tags":["audits"],"security":[{"bearer":["findings:read"]}],"x-required-scope":"findings:read","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/audits/{audit_id}/export":{"get":{"operationId":"audits.export","summary":"Export audit report","description":"Export an audit report as JSON or CSV, including methodology, coverage, every finding with its financial classification and assumptions.\n\nMCP tool: `audit_export`. UI: `/app/audits/{audit_id}#export`.","tags":["audits"],"security":[{"bearer":["audits:read"]}],"x-required-scope":"audits:read","parameters":[{"name":"audit_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"format","in":"query","required":false,"schema":{"default":"json","type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/findings":{"get":{"operationId":"findings.list","summary":"List findings","description":"List findings with filters (class, status, severity, owner, title search). Each finding carries a financial_classification — only \"verified_saving\" is money actually saved.\n\nMCP tool: `findings_list`. UI: `/app/findings`.","tags":["findings"],"security":[{"bearer":["findings:read"]}],"x-required-scope":"findings:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["candidate","needs_validation","validated_opportunity","experiment_running","verified_saving","dismissed","not_actionable"]}},{"name":"financial_classification","in":"query","required":false,"schema":{"type":"string","enum":["observed_spend","anomalous_spend","potential_saving","validated_opportunity","verified_saving"]}},{"name":"severity","in":"query","required":false,"schema":{"type":"string","enum":["info","low","medium","high","critical"]}},{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":100}},{"name":"include_dismissed","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]}},{"name":"assignee","in":"query","required":false,"schema":{"description":"Owner filter: \"me\" (the person behind the calling credential), \"unassigned\", or a member user id","anyOf":[{"type":"string","enum":["me","unassigned"]},{"type":"string","pattern":"^usr_[a-z0-9]{6,40}$"}]}},{"name":"sort","in":"query","required":false,"schema":{"default":"recent","description":"impact = severity, then amount; cursor pagination applies to recent only","type":"string","enum":["recent","impact"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/findings/{finding_id}":{"get":{"operationId":"findings.get","summary":"Get finding","description":"Get a finding with evidence, assumptions, confidence, linked source cost records (up to 50), notes and history.\n\nMCP tool: `finding_get`. UI: `/app/findings/{finding_id}`.","tags":["findings"],"security":[{"bearer":["findings:read"]}],"x-required-scope":"findings:read","parameters":[{"name":"finding_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"findings.update","summary":"Update finding","description":"Assign a finding to a member, snooze it until a date, or change its status. Only a potential saving can become a validated opportunity, and that needs a validation_note explaining the evidence. Anomalous or observed spend is not a savings amount: propose a fix (optimization_create) instead. Cannot set verified_saving (use optimization_verify).\n\nMCP tool: `finding_update`. UI: `/app/findings/{finding_id}`.","tags":["findings"],"security":[{"bearer":["findings:write"]}],"x-required-scope":"findings:write","parameters":[{"name":"finding_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"assignee_user_id":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"snoozed_until":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]},"status":{"type":"string","enum":["candidate","needs_validation","validated_opportunity","not_actionable"]},"validation_note":{"type":"string","minLength":10,"maxLength":2000}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/findings/{finding_id}/acknowledge":{"post":{"operationId":"findings.acknowledge","summary":"Acknowledge finding","description":"Mark a finding as seen/acknowledged.\n\nMCP tool: `finding_acknowledge`. UI: `/app/findings/{finding_id}`.","tags":["findings"],"security":[{"bearer":["findings:write"]}],"x-required-scope":"findings:write","parameters":[{"name":"finding_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/findings/{finding_id}/dismiss":{"post":{"operationId":"findings.dismiss","summary":"Dismiss finding","description":"Dismiss a finding with a required reason. Evidence is preserved; recurring audits will not reopen it.\n\nMCP tool: `finding_dismiss`. UI: `/app/findings/{finding_id}`.","tags":["findings"],"security":[{"bearer":["findings:write"]}],"x-required-scope":"findings:write","parameters":[{"name":"finding_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":1000}},"required":["reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/findings/{finding_id}/reopen":{"post":{"operationId":"findings.reopen","summary":"Reopen finding","description":"Reopen a dismissed or not-actionable finding.\n\nMCP tool: `finding_reopen`. UI: `/app/findings/{finding_id}`.","tags":["findings"],"security":[{"bearer":["findings:write"]}],"x-required-scope":"findings:write","parameters":[{"name":"finding_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/findings/{finding_id}/notes":{"post":{"operationId":"findings.add_note","summary":"Annotate finding","description":"Add a plain-text note to a finding (stored as data; never interpreted as instructions).\n\nMCP tool: `finding_add_note`. UI: `/app/findings/{finding_id}`.","tags":["findings"],"security":[{"bearer":["findings:write"]}],"x-required-scope":"findings:write","parameters":[{"name":"finding_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"body":{"type":"string","minLength":1,"maxLength":4000}},"required":["body"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/spend/summary":{"get":{"operationId":"spend.summary","summary":"Spend summary","description":"Observed billed spend for the period (per currency), data freshness, and — kept strictly separate — potential/validated opportunity amounts from open findings, the combined potential with overlap removed (an estimate, never a plain sum) and confirmed (verified) savings.\n\nMCP tool: `spend_get_summary`. UI: `/app/overview`.","tags":["spend"],"security":[{"bearer":["spend:read"]}],"x-required-scope":"spend:read","parameters":[{"name":"period_days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":365}},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["openai","anthropic","xai","demo"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/spend/timeseries":{"get":{"operationId":"spend.timeseries","summary":"Spend time series","description":"Daily observed spend (UTC days), optionally split by provider/project/workspace/model/category. Days with no data are returned as zero with has_data=false.\n\nMCP tool: `spend_get_timeseries`. UI: `/app/spend`.","tags":["spend"],"security":[{"bearer":["spend:read"]}],"x-required-scope":"spend:read","parameters":[{"name":"period_days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":365}},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["openai","anthropic","xai","demo"]}},{"name":"group_by","in":"query","required":false,"schema":{"default":"none","type":"string","enum":["none","provider","project","workspace","model","category"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/spend/breakdown":{"get":{"operationId":"spend.breakdown","summary":"Spend breakdown","description":"Observed spend for the period grouped by one dimension, largest first, with share of total per currency.\n\nMCP tool: `spend_get_breakdown`. UI: `/app/spend`.","tags":["spend"],"security":[{"bearer":["spend:read"]}],"x-required-scope":"spend:read","parameters":[{"name":"period_days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":365}},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["openai","anthropic","xai","demo"]}},{"name":"dimension","in":"query","required":false,"schema":{"default":"project","type":"string","enum":["provider","project","workspace","model","category","line_item"]}},{"name":"limit","in":"query","required":false,"schema":{"default":20,"type":"integer","minimum":1,"maximum":100}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/spend/unit-costs":{"get":{"operationId":"spend.unit_costs","summary":"Unit costs by model","description":"Per model: billed cost, tokens, effective cost per million tokens, cached share of input, and the change in cost per million tokens between the first and second half of the period. Models without token usage are omitted.\n\nMCP tool: `spend_get_unit_costs`. UI: `/app/spend`.","tags":["spend"],"security":[{"bearer":["spend:read"]}],"x-required-scope":"spend:read","parameters":[{"name":"period_days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":365}},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["openai","anthropic","xai","demo"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/telemetry/events":{"post":{"operationId":"telemetry.submit","summary":"Submit run/outcome telemetry","description":"Submit up to 500 redacted agent run/outcome events (schema v1). Idempotent on run_id. Prompts, outputs and PII are not accepted. Token fields follow OpenTelemetry gen_ai.usage.* naming.\n\nMCP tool: `telemetry_submit`. UI: `/app/developers#telemetry`.","tags":["telemetry"],"security":[{"bearer":["telemetry:write"]}],"x-required-scope":"telemetry:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"schema_version":{"default":"1","type":"string","const":"1"},"events":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"run_id":{"type":"string","minLength":1,"maxLength":120},"agent_id":{"type":"string","minLength":1,"maxLength":120},"workflow_id":{"type":"string","minLength":1,"maxLength":120},"started_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"ended_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"result_status":{"type":"string","enum":["succeeded","failed","abandoned","unknown"]},"result_verification":{"default":"unverified","type":"string","enum":["unverified","customer_reported","system_verified","human_reviewed"]},"estimated_provider_cost_minor":{"type":"integer","minimum":0,"maximum":1000000000},"currency":{"type":"string","minLength":3,"maxLength":3},"tool_calls":{"default":0,"type":"integer","minimum":0,"maximum":100000},"retry_count":{"default":0,"type":"integer","minimum":0,"maximum":10000},"model":{"type":"string","maxLength":120},"gen_ai.usage.input_tokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"gen_ai.usage.output_tokens":{"type":"integer","minimum":0,"maximum":9007199254740991},"metadata":{"type":"object","propertyNames":{"type":"string","pattern":"^[a-z0-9_.-]{1,40}$"},"additionalProperties":{"anyOf":[{"type":"string","maxLength":200},{"type":"number"},{"type":"boolean"}]}}},"required":["run_id","agent_id","workflow_id","started_at","result_status"],"additionalProperties":false}}},"required":["events"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/outcomes/summary":{"get":{"operationId":"outcomes.summary","summary":"Outcome summary","description":"Cost per verified successful task across workflows. Returns \"unavailable\" (never 0) when there are no verified successes or cost data is incomplete.\n\nMCP tool: `outcomes_get_summary`. UI: `/app/outcomes`.","tags":["outcomes"],"security":[{"bearer":["outcomes:read"]}],"x-required-scope":"outcomes:read","parameters":[{"name":"period_days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":365}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/outcomes/workflows":{"get":{"operationId":"outcomes.workflows","summary":"Workflow outcomes","description":"Per-workflow run counts, verified success/failure, retries, tool calls and cost per verified success.\n\nMCP tool: `outcomes_get_workflows`. UI: `/app/outcomes`.","tags":["outcomes"],"security":[{"bearer":["outcomes:read"]}],"x-required-scope":"outcomes:read","parameters":[{"name":"period_days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":1,"maximum":365}},{"name":"workflow_id","in":"query","required":false,"schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/outcomes/measure":{"get":{"operationId":"outcomes.measure_windows","summary":"Measure experiment windows from telemetry","description":"For one workflow, measure a baseline and a treatment window from outcome telemetry: verified successful runs, total runs, estimated cost (customer telemetry estimate) and p95 run duration. Returns a ready optimization_record_test input and any gaps (runs without cost, unverified runs, fewer than 30 verified successes). Read-only; nothing is recorded.\n\nMCP tool: `outcomes_measure_windows`. UI: `/app/optimizations`.","tags":["outcomes"],"security":[{"bearer":["outcomes:read"]}],"x-required-scope":"outcomes:read","parameters":[{"name":"workflow_id","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"baseline_start","in":"query","required":true,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},{"name":"baseline_end","in":"query","required":true,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},{"name":"treatment_start","in":"query","required":true,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},{"name":"treatment_end","in":"query","required":true,"schema":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"proposal_id","in":"query","required":false,"schema":{"type":"string","pattern":"^opt_[0-9a-z]+$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/optimization-proposals":{"get":{"operationId":"optimizations.list","summary":"List optimization proposals","description":"List optimization proposals with status, approvals, experiments and verified impacts.\n\nMCP tool: `optimization_list`. UI: `/app/optimizations`.","tags":["optimizations"],"security":[{"bearer":["optimizations:read"]}],"x-required-scope":"optimizations:read","parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","submitted","approved","rejected","testing","verified","invalidated"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"optimizations.create","summary":"Create optimization proposal","description":"Draft a proposed change (e.g. model routing, caching, retry policy) with an expected impact and a mandatory rollback plan. Nothing is applied to your systems.\n\nMCP tool: `optimization_create`. UI: `/app/optimizations#new`.","tags":["optimizations"],"security":[{"bearer":["optimizations:write"]}],"x-required-scope":"optimizations:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":160},"description":{"type":"string","minLength":10,"maxLength":4000},"change_type":{"type":"string","enum":["model_routing","prompt","caching","batching","retry_policy","tool_policy","other"]},"finding_id":{"type":"string","pattern":"^fnd_[0-9a-z]+$"},"expected_impact":{"type":"string","maxLength":1000},"rollback_plan":{"type":"string","minLength":10,"maxLength":2000},"risk_notes":{"type":"string","maxLength":2000}},"required":["title","description","change_type","rollback_plan"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/optimization-proposals/{proposal_id}":{"get":{"operationId":"optimizations.get","summary":"Get optimization proposal","description":"Get one optimization proposal with its approval, experiments and verification ledger.\n\nMCP tool: `optimization_get`. UI: `/app/optimizations`.","tags":["optimizations"],"security":[{"bearer":["optimizations:read"]}],"x-required-scope":"optimizations:read","parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"optimizations.update","summary":"Edit optimization proposal","description":"Edit a draft or rejected proposal. Approved proposals are immutable — create a new one instead.\n\nMCP tool: `optimization_update`. UI: `/app/optimizations`.","tags":["optimizations"],"security":[{"bearer":["optimizations:write"]}],"x-required-scope":"optimizations:write","parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":3,"maxLength":160},"description":{"type":"string","minLength":10,"maxLength":4000},"expected_impact":{"type":"string","maxLength":1000},"rollback_plan":{"type":"string","minLength":10,"maxLength":2000},"risk_notes":{"type":"string","maxLength":2000}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/optimization-proposals/{proposal_id}/submit":{"post":{"operationId":"optimizations.submit","summary":"Submit for approval","description":"Submit a draft proposal for approval. Creates an approval request that an approver (optimizations:approve) must decide.\n\nMCP tool: `optimization_submit`. UI: `/app/optimizations`.","tags":["optimizations"],"security":[{"bearer":["optimizations:write"]}],"x-required-scope":"optimizations:write","parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/optimization-proposals/{proposal_id}/approve":{"post":{"operationId":"optimizations.approve","summary":"Approve proposal","description":"Human-only; the approver must be a different person from the proposer. Approve a submitted proposal for a controlled experiment. Requires optimizations:approve. Approval does not apply any change; your team runs the experiment and records results.\n\nMCP tool: `optimization_approve`. UI: `/app/optimizations`.","tags":["optimizations"],"security":[{"bearer":["optimizations:approve"]}],"x-required-scope":"optimizations:approve","parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":1000}},"required":["reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/optimization-proposals/{proposal_id}/reject":{"post":{"operationId":"optimizations.reject","summary":"Reject proposal","description":"Reject a submitted proposal with a reason.\n\nMCP tool: `optimization_reject`. UI: `/app/optimizations`.","tags":["optimizations"],"security":[{"bearer":["optimizations:approve"]}],"x-required-scope":"optimizations:approve","parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":3,"maxLength":1000}},"required":["reason"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/optimization-proposals/{proposal_id}/record-test":{"post":{"operationId":"optimizations.record_test","summary":"Record experiment results","description":"Record a controlled experiment (baseline vs treatment): cost, verified successful tasks, total tasks and optional p95 latency. Proposal must be approved.\n\nMCP tool: `optimization_record_test`. UI: `/app/optimizations`.","tags":["optimizations"],"security":[{"bearer":["optimizations:write"]}],"x-required-scope":"optimizations:write","parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"environment":{"type":"string","enum":["test","staging","production_canary","production"]},"currency":{"type":"string","minLength":3,"maxLength":3},"baseline":{"type":"object","properties":{"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"cost_minor":{"type":"integer","minimum":0,"maximum":9007199254740991},"successful_tasks":{"type":"integer","minimum":0,"maximum":9007199254740991},"total_tasks":{"type":"integer","minimum":1,"maximum":9007199254740991},"p95_latency_ms":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["start","end","cost_minor","successful_tasks","total_tasks"]},"treatment":{"type":"object","properties":{"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"cost_minor":{"type":"integer","minimum":0,"maximum":9007199254740991},"successful_tasks":{"type":"integer","minimum":0,"maximum":9007199254740991},"total_tasks":{"type":"integer","minimum":1,"maximum":9007199254740991},"p95_latency_ms":{"type":"integer","minimum":0,"maximum":9007199254740991}},"required":["start","end","cost_minor","successful_tasks","total_tasks"]},"quality_notes":{"type":"string","maxLength":2000}},"required":["environment","currency","baseline","treatment"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/optimization-proposals/{proposal_id}/verify":{"post":{"operationId":"optimizations.verify","summary":"Verify saving","description":"Human-only. Evaluate the most recent experiment (production or production_canary; recorded by a different person). Marks a VERIFIED saving only if cost per verified successful task fell without a quality (success-rate) or latency regression and with ≥30 successes per window; otherwise returns insufficient_evidence or invalidates the proposal.\n\nMCP tool: `optimization_verify`. UI: `/app/optimizations`.","tags":["optimizations"],"security":[{"bearer":["optimizations:approve"]}],"x-required-scope":"optimizations:approve","parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"experiment_id":{"type":"string","pattern":"^exp_[0-9a-z]+$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alerts":{"get":{"operationId":"alerts.list","summary":"List alert rules","description":"List spend/freshness alert rules.\n\nMCP tool: `alerts_list`. UI: `/app/alerts`.","tags":["alerts"],"security":[{"bearer":["alerts:read"]}],"x-required-scope":"alerts:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"alerts.create","summary":"Create alert rule","description":"Create an alert. Spend metrics take threshold_minor in the currency’s minor unit (USD 500/day → metric \"daily_spend\", threshold_minor 50000). day_over_day_increase_pct takes threshold_pct; data_freshness_hours takes threshold_hours.\n\nMCP tool: `alert_create`. UI: `/app/alerts#new`.","tags":["alerts"],"security":[{"bearer":["alerts:write"]}],"x-required-scope":"alerts:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"metric":{"type":"string","enum":["daily_spend","weekly_spend","monthly_spend","day_over_day_increase_pct","data_freshness_hours"]},"threshold_minor":{"type":"integer","minimum":1,"maximum":10000000000000},"threshold_pct":{"type":"integer","minimum":1,"maximum":10000},"threshold_hours":{"type":"integer","minimum":1,"maximum":720},"currency":{"type":"string","minLength":3,"maxLength":3},"filters":{"default":{},"type":"object","properties":{"provider":{"type":"string","enum":["openai","anthropic","xai","demo"]},"projectId":{"type":"string","maxLength":120},"model":{"type":"string","maxLength":120},"workspaceId":{"type":"string","maxLength":120}},"additionalProperties":false},"channels":{"default":["in_app"],"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["in_app","email","webhook"]}}},"required":["name","metric"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alerts/{alert_id}":{"get":{"operationId":"alerts.get","summary":"Get alert rule","description":"Get one alert rule and its 20 most recent events.\n\nMCP tool: `alert_get`. UI: `/app/alerts`.","tags":["alerts"],"security":[{"bearer":["alerts:read"]}],"x-required-scope":"alerts:read","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"alerts.update","summary":"Update alert rule","description":"Edit, enable/disable or snooze an alert rule.\n\nMCP tool: `alert_update`. UI: `/app/alerts`.","tags":["alerts"],"security":[{"bearer":["alerts:write"]}],"x-required-scope":"alerts:write","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":120},"enabled":{"type":"boolean"},"threshold_minor":{"type":"integer","minimum":1,"maximum":10000000000000},"threshold_pct":{"type":"integer","minimum":1,"maximum":10000},"threshold_hours":{"type":"integer","minimum":1,"maximum":720},"filters":{"type":"object","properties":{"provider":{"type":"string","enum":["openai","anthropic","xai","demo"]},"projectId":{"type":"string","maxLength":120},"model":{"type":"string","maxLength":120},"workspaceId":{"type":"string","maxLength":120}},"additionalProperties":false},"channels":{"minItems":1,"maxItems":3,"type":"array","items":{"type":"string","enum":["in_app","email","webhook"]}},"snoozed_until":{"anyOf":[{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"alerts.delete","summary":"Delete alert rule","description":"Delete an alert rule and its event history.\n\nMCP tool: `alert_delete`. UI: `/app/alerts`.","tags":["alerts"],"security":[{"bearer":["alerts:write"]}],"x-required-scope":"alerts:write","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alerts/{alert_id}/dry-run":{"post":{"operationId":"alerts.dry_run","summary":"Dry-run alert rule","description":"Preview when an existing rule WOULD have fired over the last N complete days (default 30). Sends nothing.\n\nMCP tool: `alert_dry_run`. UI: `/app/alerts`.","tags":["alerts"],"security":[{"bearer":["alerts:read"]}],"x-required-scope":"alerts:read","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"lookback_days":{"default":30,"type":"integer","minimum":1,"maximum":90}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alerts/{alert_id}/test":{"post":{"operationId":"alerts.test","summary":"Send test alert","description":"Send a clearly labeled [TEST] alert through the rule’s channels to verify delivery.\n\nMCP tool: `alert_test`. UI: `/app/alerts`.","tags":["alerts"],"security":[{"bearer":["alerts:write"]}],"x-required-scope":"alerts:write","parameters":[{"name":"alert_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alert-events":{"get":{"operationId":"alerts.events","summary":"List alert events","description":"List triggered alert events, newest first.\n\nMCP tool: `alert_events_list`. UI: `/app/alerts#events`.","tags":["alerts"],"security":[{"bearer":["alerts:read"]}],"x-required-scope":"alerts:read","parameters":[{"name":"unacknowledged_only","in":"query","required":false,"schema":{"anyOf":[{"type":"boolean"},{"type":"string","enum":["0","1","true","false"]}]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alert-events/{event_id}/acknowledge":{"post":{"operationId":"alerts.acknowledge_event","summary":"Acknowledge alert event","description":"Acknowledge a triggered alert event.\n\nMCP tool: `alert_event_acknowledge`. UI: `/app/alerts#events`.","tags":["alerts"],"security":[{"bearer":["alerts:write"]}],"x-required-scope":"alerts:write","parameters":[{"name":"event_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alert-events/acknowledge":{"post":{"operationId":"alerts.acknowledge_all","summary":"Acknowledge all alert events","description":"Acknowledge every unacknowledged alert event, or only those of one rule (rule_id). Returns how many were acknowledged.\n\nMCP tool: `alert_events_acknowledge_all`. UI: `/app/alerts#events`.","tags":["alerts"],"security":[{"bearer":["alerts:write"]}],"x-required-scope":"alerts:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"rule_id":{"type":"string","pattern":"^alr_[0-9a-z]+$"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/alerts/suggest-threshold":{"get":{"operationId":"alerts.suggest_threshold","summary":"Suggest an alert threshold","description":"Suggest a threshold from your own history so an alert catches spikes without firing on ordinary days: daily and week-to-date from the last 28 complete days (max of p90 × 1.25 and median × 1.5), month-to-date from the monthly budget when set. Returns how often it would have fired over that history. Nothing is created.\n\nMCP tool: `alert_suggest_threshold`. UI: `/app/alerts#new`.","tags":["alerts"],"security":[{"bearer":["alerts:read"]}],"x-required-scope":"alerts:read","parameters":[{"name":"metric","in":"query","required":false,"schema":{"default":"daily_spend","type":"string","enum":["daily_spend","weekly_spend","monthly_spend","day_over_day_increase_pct","data_freshness_hours"]}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":3}},{"name":"provider","in":"query","required":false,"schema":{"type":"string","enum":["openai","anthropic","xai","demo"]}},{"name":"project_id","in":"query","required":false,"schema":{"type":"string","maxLength":120}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/plans":{"get":{"operationId":"billing.list_plans","summary":"List plans","description":"List plans, indicative prices (USD, billed annually) and entitlements. Taxes may apply and are shown at checkout.\n\nMCP tool: `billing_list_plans`. UI: `/pricing`.","tags":["billing"],"security":[{},{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/plan":{"get":{"operationId":"billing.get_plan","summary":"Get current plan","description":"Current plan, subscription status, renewal/cancellation state and whether payments are live, test-mode or not configured.\n\nMCP tool: `billing_get_plan`. UI: `/app/billing`.","tags":["billing"],"security":[{"bearer":["billing:read"]}],"x-required-scope":"billing:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/usage":{"get":{"operationId":"billing.usage","summary":"Plan usage","description":"Usage against plan limits: connections, alert rules, seats, webhook endpoints, audits.\n\nMCP tool: `billing_get_usage`. UI: `/app/billing`.","tags":["billing"],"security":[{"bearer":["billing:read"]}],"x-required-scope":"billing:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/checkout-session":{"post":{"operationId":"billing.checkout","summary":"Create checkout link","description":"Create a provider-hosted checkout link for a plan. A human completes payment there; card details never pass through Audon or agents. Requires current Terms and Billing policy acceptance.\n\nMCP tool: `billing_create_checkout_link`. UI: `/app/billing`.","tags":["billing"],"security":[{"bearer":["billing:write"]}],"x-required-scope":"billing:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"plan":{"type":"string","enum":["starter","growth"]}},"required":["plan"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/portal-session":{"post":{"operationId":"billing.portal","summary":"Create billing management link","description":"Create a provider-hosted billing portal link to update payment method, download invoices or change plan.\n\nMCP tool: `billing_create_management_link`. UI: `/app/billing`.","tags":["billing"],"security":[{"bearer":["billing:write"]}],"x-required-scope":"billing:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/invoices":{"get":{"operationId":"billing.invoices","summary":"List invoices","description":"List invoices from the payment provider.\n\nMCP tool: `billing_list_invoices`. UI: `/app/billing`.","tags":["billing"],"security":[{"bearer":["billing:read"]}],"x-required-scope":"billing:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/billing/cancel":{"post":{"operationId":"billing.cancel","summary":"Cancel subscription","description":"Cancel the subscription at the end of the current paid period (or resume with resume=true). Returns the provider-confirmed state; access continues until access_until. Billing contacts receive a confirmation email.\n\nMCP tool: `billing_cancel_subscription`. UI: `/app/billing`.","tags":["billing"],"security":[{"bearer":["billing:write"]}],"x-required-scope":"billing:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"resume":{"default":false,"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/developer/api-keys":{"get":{"operationId":"developer.list_keys","summary":"List API keys","description":"List API keys (prefix, scopes, last used). Secrets are never returned after creation.\n\nMCP tool: `developer_list_keys`. UI: `/app/developers#keys`.","tags":["developer"],"security":[{"bearer":["developer:read"]}],"x-required-scope":"developer:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"developer.create_key","summary":"Create API key","description":"Create a scoped API key. The secret is returned ONCE in this response; store it securely. Keys act with the creator’s authority, narrowed to the requested scopes. Signed-in people only: agents and API keys receive forbidden.\n\nMCP tool: `developer_create_key`. UI: `/app/developers#keys`.","tags":["developer"],"security":[{"bearer":["developer:write"]}],"x-required-scope":"developer:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":2,"maxLength":80},"scopes":{"minItems":1,"maxItems":31,"type":"array","items":{"type":"string","enum":["org:read","org:write","org:delete","team:read","team:write","connections:read","connections:write","audits:read","audits:write","spend:read","findings:read","findings:write","outcomes:read","telemetry:write","optimizations:read","optimizations:write","optimizations:approve","alerts:read","alerts:write","billing:read","billing:write","developer:read","developer:write","activity:read","settings:read","settings:write","notifications:write","privacy:read","privacy:write","legal:read","legal:accept"]}},"expires_in_days":{"type":"integer","minimum":1,"maximum":730}},"required":["name","scopes"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/developer/api-keys/{key_id}/rotate":{"post":{"operationId":"developer.rotate_key","summary":"Rotate API key","description":"Revoke an API key and issue a replacement with the same name and scopes. The new secret is shown once. Signed-in people only: agents and API keys receive forbidden.\n\nMCP tool: `developer_rotate_key`. UI: `/app/developers#keys`.","tags":["developer"],"security":[{"bearer":["developer:write"]}],"x-required-scope":"developer:write","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/developer/api-keys/{key_id}":{"delete":{"operationId":"developer.revoke_key","summary":"Revoke API key","description":"Revoke an API key immediately.\n\nMCP tool: `developer_revoke_key`. UI: `/app/developers#keys`.","tags":["developer"],"security":[{"bearer":["developer:write"]}],"x-required-scope":"developer:write","parameters":[{"name":"key_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/developer/agent-connections":{"get":{"operationId":"developer.list_agent_connections","summary":"List agent connections","description":"List OAuth-connected agents/MCP clients, their scopes and last use.\n\nMCP tool: `agent_connections_list`. UI: `/app/developers#agents`.","tags":["developer"],"security":[{"bearer":["developer:read"]}],"x-required-scope":"developer:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/developer/agent-connections/{agent_connection_id}/revoke":{"post":{"operationId":"developer.revoke_agent_connection","summary":"Revoke agent connection","description":"Revoke an agent connection; all its access and refresh tokens stop working immediately.\n\nMCP tool: `agent_connection_revoke`. UI: `/app/developers#agents`.","tags":["developer"],"security":[{"bearer":["developer:write"]}],"x-required-scope":"developer:write","parameters":[{"name":"agent_connection_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks":{"get":{"operationId":"webhooks.list","summary":"List webhooks","description":"List webhook endpoints and recent delivery outcomes.\n\nMCP tool: `webhook_list`. UI: `/app/developers#webhooks`.","tags":["webhooks"],"security":[{"bearer":["developer:read"]}],"x-required-scope":"developer:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"webhooks.create","summary":"Create webhook","description":"Register an HTTPS webhook endpoint. Payloads are signed (header x-aa-signature: t=…,v1=HMAC-SHA256). The signing secret is returned once.\n\nMCP tool: `webhook_create`. UI: `/app/developers#webhooks`.","tags":["webhooks"],"security":[{"bearer":["developer:write"]}],"x-required-scope":"developer:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri"},"events":{"minItems":1,"type":"array","items":{"type":"string","enum":["audit.completed","finding.created","finding.updated","alert.triggered","optimization.approved","optimization.verified","connection.degraded","subscription.updated","*"]}}},"required":["url","events"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhooks/{webhook_id}":{"patch":{"operationId":"webhooks.update","summary":"Update webhook","description":"Change a webhook’s URL, events or enabled state.\n\nMCP tool: `webhook_update`. UI: `/app/developers#webhooks`.","tags":["webhooks"],"security":[{"bearer":["developer:write"]}],"x-required-scope":"developer:write","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":500,"format":"uri"},"events":{"minItems":1,"type":"array","items":{"type":"string"}},"enabled":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"operationId":"webhooks.delete","summary":"Delete webhook","description":"Delete a webhook endpoint.\n\nMCP tool: `webhook_delete`. UI: `/app/developers#webhooks`.","tags":["webhooks"],"security":[{"bearer":["developer:write"]}],"x-required-scope":"developer:write","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/activity":{"get":{"operationId":"activity.list","summary":"List activity","description":"Tamper-evident activity log of every human, API key, agent and system action (actor, channel, target, time).\n\nMCP tool: `activity_list`. UI: `/app/activity`.","tags":["activity"],"security":[{"bearer":["activity:read"]}],"x-required-scope":"activity:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":50,"type":"integer","minimum":1,"maximum":200}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"action","in":"query","required":false,"schema":{"type":"string","maxLength":80}},{"name":"actor_type","in":"query","required":false,"schema":{"type":"string","enum":["user","api_key","agent","system","job"]}},{"name":"channel","in":"query","required":false,"schema":{"type":"string","enum":["web","rest","mcp","system"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/activity/verify":{"get":{"operationId":"activity.verify_chain","summary":"Verify activity log integrity","description":"Recompute the activity hash chain and report whether any event was altered or removed.\n\nMCP tool: `activity_verify`. UI: `/app/activity`.","tags":["activity"],"security":[{"bearer":["activity:read"]}],"x-required-scope":"activity:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/settings":{"get":{"operationId":"settings.get","summary":"Get settings","description":"Organization settings: timezone, display currency, retention, monthly budget, billing email and data-use controls.\n\nMCP tool: `settings_get`. UI: `/app/settings`.","tags":["settings"],"security":[{"bearer":["settings:read"]}],"x-required-scope":"settings:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"settings.update","summary":"Update settings","description":"Update retention (30 days up to your plan’s limit; older spend, usage and telemetry is deleted daily), monthly budget (minor units, used by budget detectors) and billing email.\n\nMCP tool: `settings_update`. UI: `/app/settings`.","tags":["settings"],"security":[{"bearer":["settings:write"]}],"x-required-scope":"settings:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"retention_days":{"type":"integer","minimum":30,"maximum":2555},"monthly_budget_minor":{"anyOf":[{"type":"integer","minimum":0,"maximum":10000000000000},{"type":"null"}]},"budget_currency":{"type":"string","minLength":3,"maxLength":3},"billing_email":{"anyOf":[{"type":"string","maxLength":200,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},{"type":"null"}]}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/settings/notifications":{"get":{"operationId":"notifications.get_preferences","summary":"Get my notification preferences","description":"The calling user’s own email preferences for this organization (alert emails; the weekly review email, off by default; product updates — marketing — off by default). Any member can manage their own.\n\nMCP tool: `notification_preferences_get`. UI: `/app/settings#notifications`.","tags":["notifications"],"security":[{"bearer":["settings:read"]}],"x-required-scope":"settings:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"notifications.update_preferences","summary":"Update my notification preferences","description":"Change the calling user’s own email preferences. Requires notifications:write. Agents and API keys can turn product-update (marketing) email OFF but never ON: marketing consent is only recorded from the person themselves.\n\nMCP tool: `notification_preferences_update`. UI: `/app/settings#notifications`.","tags":["notifications"],"security":[{"bearer":["notifications:write"]}],"x-required-scope":"notifications:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"email_alerts":{"type":"boolean"},"email_weekly_digest":{"type":"boolean"},"email_product_updates":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data-rights":{"get":{"operationId":"privacy.get","summary":"Get data rights & controls","description":"Data-use controls (raw trace capture, research use — both OFF by default), retention, open export/deletion requests and the subprocessor list link.\n\nMCP tool: `data_rights_get`. UI: `/app/settings#data`.","tags":["privacy"],"security":[{"bearer":["privacy:read"]}],"x-required-scope":"privacy:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"operationId":"privacy.update","summary":"Update data-use controls","description":"Turn data-use controls OFF. Enabling raw trace capture or research data use is not available self-serve: research use requires a separate written agreement, and raw capture is not offered in this release.\n\nMCP tool: `data_rights_update`. UI: `/app/settings#data`.","tags":["privacy"],"security":[{"bearer":["privacy:write"]}],"x-required-scope":"privacy:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"raw_trace_capture":{"type":"boolean"},"research_data_use":{"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data-export":{"post":{"operationId":"privacy.export","summary":"Export organization data","description":"Export all of the organization’s data as JSON: one section per organization-scoped table (settings, members, connections metadata, audits, findings and notes, alerts and events, optimizations, experiments and approvals, runs, spend and usage records, activity log, API key and agent connection metadata, webhooks, consents, legal acceptances, data requests, notification preferences, billing records). Secrets, credential hashes and ciphertexts are never included. Logged and returned directly.\n\nMCP tool: `data_export`. UI: `/app/settings#data`.","tags":["privacy"],"security":[{"bearer":["privacy:write"]}],"x-required-scope":"privacy:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"include_spend_records":{"default":true,"type":"boolean"}},"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/data-deletion-request":{"post":{"operationId":"privacy.delete_request","summary":"Request data deletion","description":"Delete a category of data now (\"telemetry\" runs, or \"spend_data\" for disconnected connections). Whole-organization deletion uses organization_delete (owner confirmation).\n\nMCP tool: `data_delete_request`. UI: `/app/settings#data`.","tags":["privacy"],"security":[{"bearer":["privacy:write"]}],"x-required-scope":"privacy:write","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"scope":{"type":"string","enum":["telemetry","spend_data_disconnected"]},"reason":{"type":"string","maxLength":500}},"required":["scope"],"additionalProperties":false}}}},"responses":{"202":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/legal/documents":{"get":{"operationId":"legal.list","summary":"List legal documents","description":"List current legal documents (id, version, hash, status) and which require acceptance.\n\nMCP tool: `legal_list_documents`. UI: `/terms`.","tags":["legal"],"security":[{},{"bearer":[]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/legal/documents/{document_id}":{"get":{"operationId":"legal.get","summary":"Read legal document","description":"Read the full Markdown text of a legal document at its current version, with its hash (pass both to legal_accept).\n\nMCP tool: `legal_get_document`. UI: `/terms`.","tags":["legal"],"security":[{},{"bearer":[]}],"parameters":[{"name":"document_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/legal/acceptances":{"get":{"operationId":"legal.required","summary":"Required acceptances","description":"List legal documents this organization still needs to accept at their current version, plus past acceptance records.\n\nMCP tool: `legal_required_acceptances`. UI: `/app/settings#legal`.","tags":["legal"],"security":[{"bearer":["legal:read"]}],"x-required-scope":"legal:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"post":{"operationId":"legal.accept","summary":"Accept legal document","description":"Accept a legal document on behalf of the organization. Pass the exact version and hash you read with legal_get_document and an authority statement. Requires legal:accept. Agents and API keys receive approval_required: nothing is accepted until a signed-in owner or billing admin confirms the request (legal_decide_acceptance or Settings → Legal records).\n\nMCP tool: `legal_accept`. UI: `/app/settings#legal`.","tags":["legal"],"security":[{"bearer":["legal:accept"]}],"x-required-scope":"legal:accept","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"document_id":{"type":"string","maxLength":40},"version":{"type":"string","maxLength":40},"hash":{"type":"string","minLength":64,"maxLength":64},"authority_statement":{"type":"string","minLength":10,"maxLength":500,"description":"e.g. \"I am authorised to bind <org> to these terms.\""},"context":{"default":"update_prompt","type":"string","enum":["signup","checkout","dpa_execution","update_prompt"]}},"required":["document_id","version","hash","authority_statement"],"additionalProperties":false}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/legal/approvals/{approval_id}/decide":{"post":{"operationId":"legal.decide_acceptance","summary":"Confirm or reject a requested legal acceptance","description":"Confirm (approve=true) or reject a legal acceptance that an agent or API key requested. Signed-in owners and billing admins only; confirming records the acceptance in your name with your authority statement.\n\nMCP tool: `legal_decide_acceptance`. UI: `/app/settings#legal`.","tags":["legal"],"security":[{"bearer":["legal:accept"]}],"x-required-scope":"legal:accept","parameters":[{"name":"approval_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approve":{"type":"boolean"},"authority_statement":{"description":"Required when approving, e.g. \"I am authorised to bind <org> to these terms.\"","type":"string","minLength":10,"maxLength":500},"reason":{"type":"string","maxLength":500}},"required":["approve"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/invites/accept":{"post":{"operationId":"team.accept_invite","summary":"Accept invitation","description":"Accept an invitation token as the signed-in user. The invite email must match the user’s verified email.\n\nMCP tool: `team_accept_invite`. UI: `/invite/{token}`.","tags":["team"],"security":[{},{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":120},"description":"Replays return the original response; reuse with a different body returns 409."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","minLength":10,"maxLength":200}},"required":["token"],"additionalProperties":false}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/account":{"delete":{"operationId":"account.delete","summary":"Delete my account","description":"Permanently delete the signed-in person’s own user account: memberships, sessions, notification preferences, and their API keys and agent connections. Signed-in people only (agents and API keys receive forbidden). Refused while you are the only owner of an organization that still exists: delete it or make someone else an owner first. Pass confirm_email equal to your account email.\n\nMCP tool: `account_delete`. UI: `/app/settings#account`.","tags":["account"],"security":[{},{"bearer":[]}],"parameters":[{"name":"confirm_email","in":"query","required":true,"schema":{"type":"string","maxLength":200}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/savings/plan":{"get":{"operationId":"savings.plan","summary":"Get savings plan","description":"Savings levers sized on your data (potential savings under stated scenarios, listed individually and never summed), the pipeline from potential to verified, whether each verified saving is holding (savings guard), and the provider facts each lever uses with sources.\n\nMCP tool: `savings_get_plan`. UI: `/app/savings`.","tags":["savings"],"security":[{"bearer":["findings:read"]}],"x-required-scope":"findings:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/savings/export":{"get":{"operationId":"savings.export","summary":"Export savings plan","description":"The savings plan as CSV for finance: one row per opportunity with lever, scope, evidence class, stage, amount, scenario share and savings-guard status. Potential savings overlap and must not be summed; the file says so in its first lines.\n\nMCP tool: `savings_export_plan`. UI: `/app/savings`.","tags":["savings"],"security":[{"bearer":["findings:read"]}],"x-required-scope":"findings:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/savings/next-fix":{"get":{"operationId":"savings.next_fix","summary":"Get the next fix","description":"The largest open potential saving (or validated opportunity) that has no live proposal, or the finding you name, with exact steps, rollback, experiment design, what verification requires and a ready optimization_create input. A scenario, not a saving: only an approved, measured experiment verifies it. Audon never applies the change.\n\nMCP tool: `savings_get_next_fix`. UI: `/app/savings`.","tags":["savings"],"security":[{"bearer":["findings:read"]}],"x-required-scope":"findings:read","parameters":[{"name":"finding_id","in":"query","required":false,"schema":{"type":"string","pattern":"^fnd_[0-9a-z]+$"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/spend/forecast":{"get":{"operationId":"spend.forecast","summary":"Month-end spend forecast","description":"Month-to-date observed spend (complete UTC days) and a month-end range per currency: remaining days valued at the 20th/50th/80th percentile of the last 28 complete days. Compared with the monthly budget (within_budget, at_risk, likely_over, no_budget, insufficient_history). An empirical range, not a confidence interval; never a saving.\n\nMCP tool: `spend_get_forecast`. UI: `/app/spend#forecast`.","tags":["spend"],"security":[{"bearer":["spend:read"]}],"x-required-scope":"spend:read","parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/digest":{"get":{"operationId":"insights.digest","summary":"What changed (weekly review)","description":"What changed in the last N days (default 7): observed spend vs the previous N complete days with the top movers, new findings counted per evidence class, proposals that moved, savings verified (summed per currency), verified savings slipping, alerts fired, and a one-sentence headline.\n\nMCP tool: `digest_get`. UI: `/app/review`.","tags":["insights"],"security":[{"bearer":["spend:read"]}],"x-required-scope":"spend:read","parameters":[{"name":"days","in":"query","required":false,"schema":{"default":7,"type":"integer","minimum":1,"maximum":31}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/next-actions":{"get":{"operationId":"insights.next_actions","summary":"Next actions","description":"The ranked next steps across the whole loop (fix data, decide, verify, keep, plan the largest fix, set up alerts/budget/telemetry). Each item has a reason, an app link, the exact MCP tool and input that performs it, and whether a person must do it. Start here.\n\nMCP tool: `next_actions_list`. UI: `/app/overview`.","tags":["insights"],"security":[{"bearer":["findings:read"]}],"x-required-scope":"findings:read","parameters":[{"name":"limit","in":"query","required":false,"schema":{"default":10,"type":"integer","minimum":1,"maximum":50}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/reports/finance-summary":{"get":{"operationId":"reports.finance_summary","summary":"Finance summary","description":"A one-page summary for finance: observed spend by provider, month-end forecast vs budget, verified savings with method (the only money saved), validated opportunities, the combined potential with overlap removed (estimate) and the largest levers individually, anomalies to review, data freshness and the evidence-class definitions. format=json|csv|markdown; synthetic data is labelled.\n\nMCP tool: `finance_summary_get`. UI: `/app/finance`.","tags":["reports"],"security":[{"bearer":["spend:read"]}],"x-required-scope":"spend:read","parameters":[{"name":"period_days","in":"query","required":false,"schema":{"default":30,"type":"integer","minimum":7,"maximum":365}},{"name":"format","in":"query","required":false,"schema":{"default":"json","type":"string","enum":["json","csv","markdown"]}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/optimization-proposals/{proposal_id}/proof":{"get":{"operationId":"optimizations.proof","summary":"Proof of a change","description":"One proposal from finding to verified saving: each step (planned, approved by a second person, measured and recorded, verified) with who and when; the next step with the exact tool and input; suggested baseline and treatment windows with the matching workflows measured from outcome telemetry (a ready optimization_record_test input); and, once an experiment is recorded, a preview of what verification would conclude. Read-only: nothing is recorded or verified.\n\nMCP tool: `optimization_get_proof`. UI: `/app/optimizations/{proposal_id}`.","tags":["optimizations"],"security":[{"bearer":["optimizations:read"]}],"x-required-scope":"optimizations:read","parameters":[{"name":"proposal_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"workflow_id","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":120}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"operation":{"type":"string"}}}}}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"API key (aa_live_…) or OAuth access token. Scopes: org:read (View organization details); org:write (Edit organization details); org:delete (Request organization deletion); team:read (View members and invitations); team:write (Invite, change roles and remove members); connections:read (View provider connections and sync health); connections:write (Connect, test, sync, rotate and disconnect providers); audits:read (View audits and exports); audits:write (Start, retry and cancel audits); spend:read (Read normalized spend); findings:read (View findings and evidence); findings:write (Acknowledge, dismiss, reopen and annotate findings); outcomes:read (Read outcome and cost-per-success reports); telemetry:write (Submit agent run / outcome telemetry); optimizations:read (View optimization proposals and experiments); optimizations:write (Create proposals and record experiment results); optimizations:approve (Approve or reject optimization proposals and verify savings); alerts:read (View alert rules and events); alerts:write (Create, edit, test and acknowledge alerts); billing:read (View plan, usage and invoices); billing:write (Start checkout, manage or cancel subscription); developer:read (View API keys, agent connections and webhooks); developer:write (Create/rotate/revoke API keys, agent connections and webhooks); activity:read (Read the activity (audit) log); settings:read (Read settings); settings:write (Change organization settings); notifications:write (Change your own email notification preferences (agents can only turn marketing email off)); privacy:read (View data rights, consents and requests); privacy:write (Change consents, request exports or deletion); legal:read (Read legal documents and acceptance records); legal:accept (Accept legal documents on behalf of the organization)"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["unauthenticated","insufficient_scope","forbidden","not_found","validation_failed","conflict","rate_limited","approval_required","awaiting_external_consent","entitlement_required","insufficient_evidence","provider_error","not_configured","idempotency_conflict","internal"]},"message":{"type":"string"},"details":{"type":"object"},"request_id":{"type":"string"}}}}}}}}