Discovery

Discovery endpoints describe what is available in your tenant. They are the recommended entry points for AI agents and integrations.

• GET /api/v1/openapi.json

• GET /api/v1/manifest

• GET /api/v1/catalog

• GET /api/v1/capabilities

---

GET /api/v1/openapi.json

Return the OpenAPI 3.1 spec for /api/v1. Unauthenticated.

A second alias serves the same payload at GET /.well-known/agent-tools.json.

Response

{ "openapi": "3.1.0", "info": { "title": "Peak Commerce Agent API v1", ... }, "paths": { ... } }

cURL

curl https://api.example.com/api/v1/openapi.json

---

GET /api/v1/manifest

Return a tenant-level capability manifest: every operation the API supports, every published payment page, and the tenant's enabled capabilities (payment methods, currencies, billing integrations, catalog sizes).

• Auth scope: read

• Path params: none

• Query params: none

• Request body: none

Response 200

{
  "version": "1.0",
  "generatedAt": "2026-05-02T14:00:00Z",
  "operations": [
    {
      "operationId": "createOrder",
      "method": "POST",
      "path": "/api/v1/orders",
      "scope": "commerce",
      "description": "Create order"
    }
  ],
  "paymentPages": [
    {
      "id": "pg_01H...",
      "name": "Default Checkout",
      "slug": "checkout",
      "paymentMethods": ["card", "ach"],
      "commerceManifest": { "status": "published" }
    }
  ],
  "capabilities": {
    "paymentMethods": ["card", "ach"],
    "supportedCurrencies": ["USD"],
    "integrations": [
      { "type": "stripe", "name": "Production", "isActive": true }
    ],
    "catalogStats": { "products": 12, "offers": 3 },
    "merchantPaymentCapabilities": ["card", "ach"]
  },
  "nextActions": [
    { "rel": "catalog", "method": "GET", "href": "/api/v1/catalog" },
    { "rel": "capabilities", "method": "GET", "href": "/api/v1/capabilities" }
  ]
}

Errors

Status	When
401	Missing or invalid API key
403	Key lacks the read scope
500	Server error

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/manifest

---

GET /api/v1/catalog

Return the catalog: every product enriched with its lifecycle business rules (upgrade, downgrade, cancellation, add-on) and pricing-rule indicators, plus a summary of every payment page.

• Auth scope: read

Response 200

{
  "data": {
    "products": [
      {
        "id": "prod_01H...",
        "name": "Pro Plan",
        "sku": "PRO",
        "description": "Everything plus seats and integrations.",
        "category": "subscription",
        "productType": "plan",
        "priceCents": 4900,
        "currency": "USD",
        "billingInterval": "month",
        "isActive": true,
        "lifecycleRules": {
          "upgrade":      { "ruleId": "br_...", "ruleName": "Default upgrade", "changeTiming": "immediate", "prorationType": "prorated" },
          "downgrade":    { "ruleId": "br_...", "ruleName": "Default downgrade", "changeTiming": "at_period_end", "prorationType": "none" },
          "cancellation": null,
          "addOn":        null
        },
        "pricingRules": { "hasDynamicPricing": true, "pricingTierCount": 3 }
      }
    ],
    "paymentPages": [
      {
        "id": "pg_01H...",
        "name": "Default Checkout",
        "slug": "checkout",
        "companyName": "Acme Inc.",
        "paymentMethods": ["card", "ach"]
      }
    ]
  },
  "nextActions": [
    { "rel": "capabilities", "method": "GET", "href": "/api/v1/capabilities" },
    { "rel": "manifest", "method": "GET", "href": "/api/v1/manifest" },
    { "rel": "createPaymentSession", "method": "POST", "href": "/api/v1/payments" }
  ]
}

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/catalog

---

GET /api/v1/capabilities

Return merchant capabilities: enabled payment methods, supported currencies, the available action set, and active billing integrations.

• Auth scope: read

Response 200

{
  "paymentMethods": ["card", "ach"],
  "supportedCurrencies": ["USD"],
  "availableActions": [
    "list_catalog", "get_capabilities", "get_manifest",
    "create_account", "get_account", "update_account",
    "list_invoices", "pay_invoice",
    "create_subscription", "change_plan", "cancel_subscription", "renew_subscription",
    "create_order", "update_order",
    "create_payment_session", "complete_payment_session",
    "list_payment_methods", "add_payment_method", "set_default_payment_method",
    "list_webhooks", "create_webhook", "update_webhook", "delete_webhook"
  ],
  "integrations": [
    { "type": "stripe", "name": "Production", "isActive": true }
  ],
  "nextActions": [
    { "rel": "capabilities", "method": "GET", "href": "/api/v1/capabilities" },
    { "rel": "manifest", "method": "GET", "href": "/api/v1/manifest" },
    { "rel": "createPaymentSession", "method": "POST", "href": "/api/v1/payments" }
  ]
}

cURL

curl -H "Authorization: Bearer $PEAK_API_KEY" \
  https://api.example.com/api/v1/capabilities

---

Related

• Accounts

• Pricing previews