Agent API

CLI&Open CLOUD agent checkout workflow

Agents can discover products, quote deterministic pricing, create a pending payment order from customer billing data, submit post-payment service install configuration, and fetch ready handoff credentials through signed API URLs.

Workflow

Recommended sequence

  1. Discover products with GET /api/products or GET /api/products/{product_id}.
  2. Quote with POST /api/checkout/quote. Check configuration_normalized and configuration_warnings; invalid limits are defaulted down instead of clamped up.
  3. If the customer agrees and billing fields are known, create an order with POST /api/order and an Idempotency-Key. Public agents use payment_method=card.
  4. Poll the returned status_url. Treat signed status like a bearer token and do not publish it; signed status is sensitive but does not include a raw bearer token.
  5. Authenticated customer-agent orders require a logged-in customer session, an explicitly issued customer-agent bearer token, or agent_auth.token_exchange metadata when available. Use Authorization: Bearer <token> only with a token issued through those flows.
  6. Authenticated customer agents may use payment_method=credit when existing account credit covers the total. Email-only public agents cannot spend customer credit.
  7. When payment is confirmed asynchronously, the status changes from Pending to Success. If a service returns requires_install_configuration=true, POST {"config": {...}} to its signed install_action.url.
  8. During processing, read provisioning_estimate. Provisioning usually takes 3-20 minutes; poll every 60 seconds and do not retry aggressively.
  9. Continue polling status_url. When credentials_available=true, fetch secrets from the signed credentials_action.url and treat the response as sensitive handoff material.
Required order fields

Billing is required before order creation

If the agent only has an email address, it should ask the customer for billing details before creating the order. The API intentionally returns validation errors instead of guessing billing data.

{
  "customer_email": "customer@example.com",
  "billing_name": "Customer Name",
  "billing_street": "Cloud Street 1",
  "billing_city": "Prague",
  "billing_postal_code": "11000",
  "billing_country": "CZ",
  "items": [
    {"product_id": "kubernetes-hosting-universal", "quantity": 1}
  ]
}
Machine docs

Discovery endpoints

OpenAPI · Agent policy · AI map · llms.txt · MCP-style tools