Amply API

Overview

Amply exposes a single decision endpoint: you send a natural-language task (plus optional workload hints), and receive a ranked recommendation with economics, latency signals, and a machine-readable why. Integrate from any stack with fetch, curl, or the SDKs below once published.

Base URL (production): https://www.useamply.com/api/v1

Authentication

Send a Bearer token on POST /api/v1/route:

# User-bound key — required for wallet tracking and cost reports
Authorization: Bearer amply_sk_your_key_here

• User keys. Sign in and create keys in the dashboard. Requires Supabase + database_setup_amply_api_keys.sql applied. Secrets are stored as SHA-256 only; the full key is shown once at creation.
• Server keys. Comma-separated AMPLY_API_KEYS (ops / shared secrets). If set, every request must present a valid env key or a valid user key.
• Require Bearer. Set AMPLY_REQUIRE_API_KEY=1 to reject anonymous requests when you have no AMPLY_API_KEYS (e.g. production with user keys only).

If nothing requires auth (local dev), requests without Authorization may still succeed. Check /api/v1/status for auth_mode and diagnostics.user_api_keys_store_ready.

Production keys & principals

For metering, prepaid wallet debit, per-principal quota, and audit scoping, callers should use a user-bound secret: either a dashboard-created key from /dashboard/api-keys (after sign-in) or an autonomous key from POST /api/v1/signup/agent when enabled.

AMPLY_API_KEYS (server env) are operator keys: they authenticate but do not attach a principal, so settlement and audit ownership behave differently. Use env keys for cron, probes, and internal tools — not as the default for customer agents.

Every successful POST /api/v1/route response with metering on includes an integration object: deep links for billing status, outcome reporting, and audit bundles; structured alerts plus a recommendation when no principal is present. Response headers include X-Amply-Principal-Bound (0 or 1), X-Amply-Auth-Source (e.g. user_key vs server_key), and when metering is on also X-Amply-Metering: on plus X-Amply-Economics (settlement_eligible vs recommendation_only_no_principal) so proxies can alert without parsing JSON. integration.economics_mode matches the economics header. GET /api/v1/status exposes diagnostics.principal_binding with policy copy and a rolling last_24h_metering_snapshot (including no_principal_pct).

Optional enforcement: set AMPLY_ROUTE_REQUIRE_PRINCIPAL_BOUND=1 to reject non-principal route calls (HTTP 403 principal_required) outside sandbox mode. Confirm rollout state via diagnostics.route_requires_principal_bound.

Agent interface (workflow + signup)

Workflow manifest. GET /api/v1/agent returns a single JSON document: ordered workflow.steps with all credential steps before GET /api/v1/providers (discover → health → schema → credential → catalog → route → outcome → audit), credential_before_catalog: true, principal_binding_policy (when to use user-bound keys vs server keys), commercial (pricing pointer, provider catalog intent / mailto, optional Stripe listing URL from env), and signup flags. Use it as the canonical bootstrap instead of parsing HTML.

Autonomous API key. When the deployment sets AMPLY_AGENT_SIGNUP=1, agents can call POST /api/v1/signup/agent with { "accept_tos_version": "…" } (must match diagnostics.agent_signup.tos_version from GET /api/v1/status). The response includes api_key once and quickstart URLs. Optional shared secret: header X-Amply-Agent-Signup-Token when AMPLY_AGENT_SIGNUP_SHARED_SECRET is set. Apply database_migration_amply_agent_signup.sql so new columns exist on amply_api_keys.

Billing model. Agents are expected to run against a prepaid balance. Deposit once, consume usage charges per request, and top up when depleted. Read response-level economics from usage and estimated_charge_usd on POST /api/v1/route.

Endpoints

v1 scope. Amply v1 is routing-first: discovery, status, providers, route, and optional outcome telemetry are stable API contracts. Payments settlement rails, enterprise policy engines, and adversarial-defense APIs are not guaranteed v1 contracts unless explicitly documented as shipped.

Outcome telemetry (freshness)

Every POST /api/v1/route response includes agent_hints.report_outcome with endpoint, route id, expected fields, and incentive metadata so agents can discover outcome reporting automatically.

Rankings improve when real execution results flow back. After you call the recommended provider, post POST /api/v1/route/outcome with the route request_id, provider_id, and an outcome enum — ideally from a background queue, not inline on your critical path.

Prefer POST /api/v1/outcome for new integrations. Request body: { route_id, success, actual_latency_ms?, error_code? }. Accepted submissions return { received: true, credits_awarded: 1 }.

Official SDKs expose routeTaskTracked (JS) / route_task_tracked (Python) as the default integration shape: route once, then call the bundled reportOutcome helper when your worker finishes.

Amply also runs scheduled synthetic probes and rolls up 30-day aggregates (see /api/v1/status outcome_telemetry and probe_cycle_cron_path). Target freshness is reflected in outcome_telemetry_target_hours — customer outcomes close the gap fastest.

Ranking transparency: POST /api/v1/route includes rankings[].confidence_sources with catalog/probe/outcome source labels for each ranked provider.

Cost constraints are available on POST /api/v1/route via budget_usd_per_1m_ops and slo_p99_ms. Constrained responses include cost_analysis and optional filtered_out.

Savings API: POST /api/v1/report with { "period": "30d" | "90d" } returns totals and a shareable summary, for example: "Amply saved your agent fleet $1,240.55 in the last 30 days."

See /dashboard/savings for a shareable monthly cost report.

OpenAPI

The machine-readable contract lives at /api/v1/openapi. Import it into Postman, Insomnia, or codegen tools. Spec version matches 3.1.13.

SDKs

Official SDKs support route decisions and optional async outcome reporting.

• TypeScript / JavaScript: amply-sdk — prefer routeTaskTracked() so you get a bound reportOutcome after each route.
• Python: amply_sdk.route_task_tracked mirrors the same pattern (report_outcome closure).

Need a reference integration (queue-based async outcome writes)? Contact us via the mission page.

Limits & errors

Optional per-IP rate limits may be enabled via AMPLY_V1_RATE_LIMIT_PER_MIN. When active, expect 429 with error: rate_limited (and optional quota_exceeded when daily per-principal route quota is configured). Invalid or missing auth returns 401 if API keys are required. The same limits surface in machine-readable form: open /api/v1/status and read rate_limit (enabled flag and requests per minute) plus auth_mode.

Wallet debit (402). When strict settlement is enabled for your principal, insufficient prepaid balance returns 402 with shortfall_usd, balance_usd, and a top_up_url hint. Check GET /api/v1/billing/status from the same user-bound key, or open Routing wallet in the dashboard.

x402 shaping (optional). When the server sets AMPLY_X402_ENABLED=1, that same 402 response adds an x402 machine-readable challenge (spec amply.x402/1) plus headers X-Amply-Payment-Required and X-Amply-X402-Spec. Successful metered routes still include integration.x402 hints for the pay → retry loop; discoverability lives in GET /api/v1/agent (workflow.x402) and OpenAPI.

One-call route + execute. POST /api/v1/route/execute runs routing first, preserves wallet/x402 semantics from route stage, then executes against the selected provider target. Use execution.mode=vault_ref with stored refs from /api/v1/credentials or execution.mode=byo_runtime with per-request targets.

Operational status: /api/v1/status · /status · Pricing & quotas

FAQ