Developers

REST API

Every capability of the app as a REST endpoint under /v1, described by an OpenAPI 3.1 specification.

Base path /v1. Authenticate with Authorization: Bearer <API key or OAuth access token>. Create keys in Developers → API keys or with POST /v1/developer/api-keys. Full schema: OpenAPI 3.1.

Quickstart

Start an audit, then list the findings it produced. Audits run in the background, so the first call returns 202.

bashStart a 30-day audit

curl -X POST https://audon.ai/v1/audits \
  -H "Authorization: Bearer $AA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "period_days": 30 }'

bashList anomalous spend

curl "https://audon.ai/v1/findings?financial_classification=anomalous_spend" \
  -H "Authorization: Bearer $AA_API_KEY"

Conventions

Responses: { "data": …, "meta": { "request_id", "operation" } }. Errors: { "error": { "code", "message", "details", "request_id" } }.
Money: amount_micros (exact integer string, 10⁻⁶ of the currency), amount_minor, amount_decimal, currency. Currencies are never summed.
Every amount on a finding carries financial_classification: observed_spend, anomalous_spend, potential_saving, validated_opportunity, verified_saving.
Long-running work returns 202; poll the returned resource (e.g. GET /v1/audits/{id}).
Send Idempotency-Key on create/execute calls. Cursor pagination via cursor / next_cursor. Timestamps are RFC 3339 UTC.

Rate limits

120 requests/minute per credential, 600 per organization by default. 429 includes Retry-After.

Errors to handle

Handle these explicitly rather than treating them as generic failures:

Code	Meaning
`approval_required`	A human approver must decide before the action runs.
`insufficient_scope`	The credential lacks the scope the operation needs.
`entitlement_required`	The organization’s plan doesn’t include this.
`insufficient_evidence`	There isn’t enough evidence to support the result, so none is given.
`not_configured`	The capability isn’t configured on this deployment.

Telemetry events

POST /v1/telemetry/events accepts up to 500 events: run_id, agent_id, workflow_id, started_at, ended_at, result_status (succeeded | failed | abandoned | unknown), result_verification (unverified | customer_reported | system_verified | human_reviewed), estimated_provider_cost_minor, currency, tool_calls, retry_count, model, gen_ai.usage.input_tokens, gen_ai.usage.output_tokens, and up to 20 operational metadata keys. Re-sending a run_id updates it.

No content in telemetry

Prompts, outputs and personal data are rejected.

Every operation

This list is generated from the same registry that powers the dashboard and the MCP server — 103 operations. The machine-readable version is capability-manifest.json in the repository.

organizations

Endpoint	Description
`POST /v1/organizations`MCP organization_create · public / user	Create a new organization. The calling user becomes its owner. Set demo=true for a clearly labeled synthetic-data sandbox.
`GET /v1/organizations`MCP organization_list · public / user	List organizations the caller can access. Token-based callers only see the organization their credential belongs to.
`GET /v1/organizations/current`MCP organization_get · org:read	Get the active organization, including plan and the caller’s role and effective scopes.
`PATCH /v1/organizations/current`MCP organization_update · org:write	Rename the organization or change country, timezone or display currency.
`DELETE /v1/organizations/current`MCP organization_delete · org:delete	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.
`POST /v1/organizations/current/cancel-deletion`MCP organization_cancel_deletion · org:delete	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.

team

Endpoint	Description
`GET /v1/members`MCP team_list · team:read	List organization members (with roles) and pending invitations.
`POST /v1/members/invite`MCP team_invite · team:write	Invite a person by email with a role (admin, analyst, billing_admin, read_only). Only owners can invite owners.
`DELETE /v1/invites/{invite_id}`MCP team_revoke_invite · team:write	Revoke a pending invitation.
`PATCH /v1/members/{member_id}`MCP team_update_member · team:write	Change a member’s role. Only owners can grant or remove the owner role; the last owner cannot be demoted.
`DELETE /v1/members/{member_id}`MCP team_remove_member · team:write	Remove a member. Their API keys and agent connections for this organization stop working immediately.
`POST /v1/invites/accept`MCP team_accept_invite · public / user	Accept an invitation token as the signed-in user. The invite email must match the user’s verified email.

connectors

Endpoint	Description
`GET /v1/connectors/catalog`MCP connector_list_available · public / user	List supported providers, the credential each needs, exactly what is read and what is never read.

connections

Endpoint	Description
`POST /v1/connections`MCP connection_create · connections:write	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.
`GET /v1/connections`MCP connection_list · connections:read	List provider connections with health, last sync and capability coverage. Secrets are never included.
`GET /v1/connections/{connection_id}`MCP connection_status · connections:read	Get one connection’s health, last sync time, last error and capabilities.
`POST /v1/connections/{connection_id}/test`MCP connection_test · connections:write	Re-validate the stored credential against the provider with a minimal read-only request.
`POST /v1/connections/{connection_id}/sync`MCP connection_sync · connections:write	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.
`POST /v1/connections/{connection_id}/rotate`MCP connection_rotate · connections:write	Replace the stored Admin API key with a new one. The new key is validated first; the old ciphertext is destroyed.
`DELETE /v1/connections/{connection_id}`MCP connection_disconnect · connections:write	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.

audits

Endpoint	Description
`POST /v1/audits`MCP audit_start · audits:write	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.
`GET /v1/audits`MCP audit_list · audits:read	List audits, newest first, with status and observed spend.
`GET /v1/audits/{audit_id}`MCP audit_get · audits:read	Get an audit’s status, progress stages, coverage, observed spend and finding counts by classification.
`POST /v1/audits/{audit_id}/retry`MCP audit_retry · audits:write	Retry a failed or cancelled audit with the same scope. Does not consume another free audit.
`POST /v1/audits/{audit_id}/cancel`MCP audit_cancel · audits:write	Cancel a queued or running audit.
`GET /v1/audits/{audit_id}/findings`MCP audit_list_findings · findings:read	List the findings produced or refreshed by one audit.
`GET /v1/audits/{audit_id}/export`MCP audit_export · audits:read	Export an audit report as JSON or CSV, including methodology, coverage, every finding with its financial classification and assumptions.

findings

Endpoint	Description
`GET /v1/findings`MCP findings_list · findings:read	List findings with filters (class, status, severity, owner, title search). Each finding carries a financial_classification — only "verified_saving" is money actually saved.
`GET /v1/findings/{finding_id}`MCP finding_get · findings:read	Get a finding with evidence, assumptions, confidence, linked source cost records (up to 50), notes and history.
`PATCH /v1/findings/{finding_id}`MCP finding_update · findings:write	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).
`POST /v1/findings/{finding_id}/acknowledge`MCP finding_acknowledge · findings:write	Mark a finding as seen/acknowledged.
`POST /v1/findings/{finding_id}/dismiss`MCP finding_dismiss · findings:write	Dismiss a finding with a required reason. Evidence is preserved; recurring audits will not reopen it.
`POST /v1/findings/{finding_id}/reopen`MCP finding_reopen · findings:write	Reopen a dismissed or not-actionable finding.
`POST /v1/findings/{finding_id}/notes`MCP finding_add_note · findings:write	Add a plain-text note to a finding (stored as data; never interpreted as instructions).

spend

Endpoint	Description
`GET /v1/spend/summary`MCP spend_get_summary · spend:read	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.
`GET /v1/spend/timeseries`MCP spend_get_timeseries · spend:read	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.
`GET /v1/spend/breakdown`MCP spend_get_breakdown · spend:read	Observed spend for the period grouped by one dimension, largest first, with share of total per currency.
`GET /v1/spend/unit-costs`MCP spend_get_unit_costs · spend:read	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.
`GET /v1/spend/forecast`MCP spend_get_forecast · spend:read	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.

telemetry

Endpoint	Description
`POST /v1/telemetry/events`MCP telemetry_submit · telemetry:write	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.

outcomes

Endpoint	Description
`GET /v1/outcomes/summary`MCP outcomes_get_summary · outcomes:read	Cost per verified successful task across workflows. Returns "unavailable" (never 0) when there are no verified successes or cost data is incomplete.
`GET /v1/outcomes/workflows`MCP outcomes_get_workflows · outcomes:read	Per-workflow run counts, verified success/failure, retries, tool calls and cost per verified success.
`GET /v1/outcomes/measure`MCP outcomes_measure_windows · outcomes:read	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.

optimizations

Endpoint	Description
`GET /v1/optimization-proposals`MCP optimization_list · optimizations:read	List optimization proposals with status, approvals, experiments and verified impacts.
`GET /v1/optimization-proposals/{proposal_id}`MCP optimization_get · optimizations:read	Get one optimization proposal with its approval, experiments and verification ledger.
`POST /v1/optimization-proposals`MCP optimization_create · optimizations:write	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.
`PATCH /v1/optimization-proposals/{proposal_id}`MCP optimization_update · optimizations:write	Edit a draft or rejected proposal. Approved proposals are immutable — create a new one instead.
`POST /v1/optimization-proposals/{proposal_id}/submit`MCP optimization_submit · optimizations:write	Submit a draft proposal for approval. Creates an approval request that an approver (optimizations:approve) must decide.
`POST /v1/optimization-proposals/{proposal_id}/approve`MCP optimization_approve · optimizations:approve	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.
`POST /v1/optimization-proposals/{proposal_id}/reject`MCP optimization_reject · optimizations:approve	Reject a submitted proposal with a reason.
`POST /v1/optimization-proposals/{proposal_id}/record-test`MCP optimization_record_test · optimizations:write	Record a controlled experiment (baseline vs treatment): cost, verified successful tasks, total tasks and optional p95 latency. Proposal must be approved.
`POST /v1/optimization-proposals/{proposal_id}/verify`MCP optimization_verify · optimizations:approve	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.
`GET /v1/optimization-proposals/{proposal_id}/proof`MCP optimization_get_proof · optimizations:read	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.

alerts

Endpoint	Description
`GET /v1/alerts`MCP alerts_list · alerts:read	List spend/freshness alert rules.
`GET /v1/alerts/{alert_id}`MCP alert_get · alerts:read	Get one alert rule and its 20 most recent events.
`POST /v1/alerts`MCP alert_create · alerts:write	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.
`PATCH /v1/alerts/{alert_id}`MCP alert_update · alerts:write	Edit, enable/disable or snooze an alert rule.
`DELETE /v1/alerts/{alert_id}`MCP alert_delete · alerts:write	Delete an alert rule and its event history.
`POST /v1/alerts/{alert_id}/dry-run`MCP alert_dry_run · alerts:read	Preview when an existing rule WOULD have fired over the last N complete days (default 30). Sends nothing.
`POST /v1/alerts/{alert_id}/test`MCP alert_test · alerts:write	Send a clearly labeled [TEST] alert through the rule’s channels to verify delivery.
`GET /v1/alert-events`MCP alert_events_list · alerts:read	List triggered alert events, newest first.
`POST /v1/alert-events/{event_id}/acknowledge`MCP alert_event_acknowledge · alerts:write	Acknowledge a triggered alert event.
`POST /v1/alert-events/acknowledge`MCP alert_events_acknowledge_all · alerts:write	Acknowledge every unacknowledged alert event, or only those of one rule (rule_id). Returns how many were acknowledged.
`GET /v1/alerts/suggest-threshold`MCP alert_suggest_threshold · alerts:read	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.

billing

Endpoint	Description
`GET /v1/billing/plans`MCP billing_list_plans · public / user	List plans, indicative prices (USD, billed annually) and entitlements. Taxes may apply and are shown at checkout.
`GET /v1/billing/plan`MCP billing_get_plan · billing:read	Current plan, subscription status, renewal/cancellation state and whether payments are live, test-mode or not configured.
`GET /v1/billing/usage`MCP billing_get_usage · billing:read	Usage against plan limits: connections, alert rules, seats, webhook endpoints, audits.
`POST /v1/billing/checkout-session`MCP billing_create_checkout_link · billing:write	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.
`POST /v1/billing/portal-session`MCP billing_create_management_link · billing:write	Create a provider-hosted billing portal link to update payment method, download invoices or change plan.
`GET /v1/billing/invoices`MCP billing_list_invoices · billing:read	List invoices from the payment provider.
`POST /v1/billing/cancel`MCP billing_cancel_subscription · billing:write	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.

developer

Endpoint	Description
`GET /v1/developer/api-keys`MCP developer_list_keys · developer:read	List API keys (prefix, scopes, last used). Secrets are never returned after creation.
`POST /v1/developer/api-keys`MCP developer_create_key · developer:write	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.
`POST /v1/developer/api-keys/{key_id}/rotate`MCP developer_rotate_key · developer:write	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.
`DELETE /v1/developer/api-keys/{key_id}`MCP developer_revoke_key · developer:write	Revoke an API key immediately.
`GET /v1/developer/agent-connections`MCP agent_connections_list · developer:read	List OAuth-connected agents/MCP clients, their scopes and last use.
`POST /v1/developer/agent-connections/{agent_connection_id}/revoke`MCP agent_connection_revoke · developer:write	Revoke an agent connection; all its access and refresh tokens stop working immediately.

webhooks

Endpoint	Description
`GET /v1/webhooks`MCP webhook_list · developer:read	List webhook endpoints and recent delivery outcomes.
`POST /v1/webhooks`MCP webhook_create · developer:write	Register an HTTPS webhook endpoint. Payloads are signed (header x-aa-signature: t=…,v1=HMAC-SHA256). The signing secret is returned once.
`PATCH /v1/webhooks/{webhook_id}`MCP webhook_update · developer:write	Change a webhook’s URL, events or enabled state.
`DELETE /v1/webhooks/{webhook_id}`MCP webhook_delete · developer:write	Delete a webhook endpoint.

activity

Endpoint	Description
`GET /v1/activity`MCP activity_list · activity:read	Tamper-evident activity log of every human, API key, agent and system action (actor, channel, target, time).
`GET /v1/activity/verify`MCP activity_verify · activity:read	Recompute the activity hash chain and report whether any event was altered or removed.

settings

Endpoint	Description
`GET /v1/settings`MCP settings_get · settings:read	Organization settings: timezone, display currency, retention, monthly budget, billing email and data-use controls.
`PATCH /v1/settings`MCP settings_update · settings:write	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.

notifications

Endpoint	Description
`GET /v1/settings/notifications`MCP notification_preferences_get · settings:read	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.
`PATCH /v1/settings/notifications`MCP notification_preferences_update · notifications:write	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.

privacy

Endpoint	Description
`GET /v1/data-rights`MCP data_rights_get · privacy:read	Data-use controls (raw trace capture, research use — both OFF by default), retention, open export/deletion requests and the subprocessor list link.
`PATCH /v1/data-rights`MCP data_rights_update · privacy:write	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.
`POST /v1/data-export`MCP data_export · privacy:write	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.
`POST /v1/data-deletion-request`MCP data_delete_request · privacy:write	Delete a category of data now ("telemetry" runs, or "spend_data" for disconnected connections). Whole-organization deletion uses organization_delete (owner confirmation).

legal

Endpoint	Description
`GET /v1/legal/documents`MCP legal_list_documents · public / user	List current legal documents (id, version, hash, status) and which require acceptance.
`GET /v1/legal/documents/{document_id}`MCP legal_get_document · public / user	Read the full Markdown text of a legal document at its current version, with its hash (pass both to legal_accept).
`GET /v1/legal/acceptances`MCP legal_required_acceptances · legal:read	List legal documents this organization still needs to accept at their current version, plus past acceptance records.
`POST /v1/legal/acceptances`MCP legal_accept · legal:accept	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).
`POST /v1/legal/approvals/{approval_id}/decide`MCP legal_decide_acceptance · legal:accept	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.

account

Endpoint	Description
`DELETE /v1/account`MCP account_delete · public / user	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.

savings

Endpoint	Description
`GET /v1/savings/plan`MCP savings_get_plan · findings:read	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.
`GET /v1/savings/export`MCP savings_export_plan · findings:read	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.
`GET /v1/savings/next-fix`MCP savings_get_next_fix · findings:read	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.

insights

Endpoint	Description
`GET /v1/digest`MCP digest_get · spend:read	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.
`GET /v1/next-actions`MCP next_actions_list · findings:read	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.

reports

Endpoint	Description
`GET /v1/reports/finance-summary`MCP finance_summary_get · spend:read	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.