Agent REST API

A versioned, governed REST API for agents (and any backend) to search, plan, price, and purchase from the catalog — with server-side policy enforcement on every write.

Basics

Base URL: /api/v1on this deployment’s origin.

Auth: send an x-api-key header on every request except /search, /openapi.json, and /health, which are public. A key with no agent principal attached acts as its owning human user (still org-scoped, still audited); a key issued to an agent principal carries that principal’s specific scopes and budgets.

Scopes: some endpoints require a named scope on the calling key (noted in the table below) — e.g. quote, purchase:request, invoke. A request missing a required scope gets back 403.

Machine-readable spec: /api/v1/openapi.json (OpenAPI 3.1) — generate a typed client from it instead of hand-maintaining one.

Endpoints (18)

Method	Path	Summary	Auth
POST	/search	Semantic catalog search	Public — x-api-key optional
GET	/products/{id}	Inspect a product (manifest, offers, licenses, trust, versions)	x-api-key
POST	/compare	Compare products across a capability matrix	x-api-key
POST	/solution-plans	Plan a multi-product solution for an objective	x-api-key
POST	/compatibility/check	Check declared compatibility between products	x-api-key
POST	/cost-estimates	Estimate one-time + recurring cost for a set of offers	x-api-key
POST	/quotes	Create a quote (server-side pricing only)	x-api-key, scope: quote
POST	/purchase-requests	Request a purchase from a quote — policy-evaluated; may require human approval	x-api-key, scope: purchase:request or purchase:auto
GET	/purchase-requests/{id}	Get purchase status; resumes an approved order idempotently	x-api-key
POST	/approval-requests	List pending approvals, or decide one (humans only)	x-api-key
POST	/provisioning-jobs	Get a provisioning job's status	x-api-key
GET	/entitlements	List the organization's entitlements	x-api-key
POST	/invocations	Invoke a purchased demo service (entitlement-gated, metered)	x-api-key, scope: invoke
GET	/usage	Usage events for the organization's entitlements	x-api-key
GET	/updates	Updates + security advisories relevant to owned entitlements	x-api-key
POST	/update-subscriptions	Subscribe to a product's update channel	x-api-key
POST	/webhooks	Register a webhook endpoint (public https, no internal targets)	x-api-key
GET	/audit-events	Recent audit events for the organization	x-api-key

Examples

1. Public search — no key required

Discovery stays open. Anonymous requests are rate-limited; sending x-api-keylifts limits and personalizes to the caller’s organization.

curl -sS -X POST https://your-deployment.example/api/v1/search \
  -H "content-type: application/json" \
  -d '{"query": "self-hosted vector database with hybrid search", "limit": 5}'

2. Create a quote — requires the `quote` scope

Pricing is always computed server-side. A quote is the priced, expiring precursor to a purchase request — never trust a client-supplied price.

curl -sS -X POST https://your-deployment.example/api/v1/quotes \
  -H "content-type: application/json" \
  -H "x-api-key: amos_agent_..." \
  -d '{"items": [{"offerId": "offr_abc123", "quantity": 1}]}'

3. Request a purchase — the approval flow

Every purchase runs through server-side policy: org policies, per-transaction and daily/monthly agent budgets, and allowlists. Two outcomes:

within policy — the order clears immediately, a demo payment executes, and entitlements are issued in the same response.
over a limit — the response comes back state: "approval_requested". A human (never the requesting agent) must call POST /approval-requests with a decision. The agent then polls GET /purchase-requests/{id}, which resumes payment and issues entitlements the moment it’s approved.

curl -sS -X POST https://your-deployment.example/api/v1/purchase-requests \
  -H "content-type: application/json" \
  -H "x-api-key: amos_agent_..." \
  -d '{"quoteId": "quot_xyz789", "idempotencyKey": "order-2026-07-31-01"}'

# → { "order": { "state": "approval_requested", ... }, "approvalRequestId": "aprv_..." }

curl -sS https://your-deployment.example/api/v1/purchase-requests/ord_... \
  -H "x-api-key: amos_agent_..."
# → resumes automatically once a human has approved

An agent credential can never decide its own approval request — that would defeat the point of governance. Only a human user key can call the decision path.