Suger API Reference

CRUD operations on a set of resources, including organizations, products, offers, entitlements, usage record groups for meterting, etc.

Base URL: https://api.suger.cloud. Most endpoints are scoped to an organization under /org/{orgId}/…, and request and response bodies are JSON (application/json). API version 1.0.

Authentication

The API uses the OAuth 2.0 client-credentials flow. Create an OAuth App to get a client ID and secret, exchange them for a short-lived (1 hour) bearer token, then send it on every request as Authorization: Bearer <token>.

curl -X POST 'https://apiv2.suger.cloud/oauth2/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'client_id=YOUR_CLIENT_ID' \
  --data-urlencode 'client_secret=YOUR_CLIENT_SECRET' \
  --data-urlencode 'resource=https://api.suger.cloud'

See API Access for the full token exchange, caching, rotation, and permissions.

Conventions

• Pagination: list endpoints commonly accept limit and offset query parameters.
• Errors: the API uses standard HTTP status codes; 4xx and 5xx responses return a JSON body describing the problem.
• Request bodies: GET and DELETE operations never take a body — pass every input as a path or query parameter. POST and PATCH operations send JSON.
• Versioning: the current API is version 2, reflected in the apiv2 host. This reference always describes the version that is deployed now.
• Rate limits: authenticated endpoints are not rate limited per request. Usage is bounded by your organization's service quotas instead.
• Idempotency: POST /org/{orgId}/offer is de-duplicated for 60 seconds. A repeat call with an identical body from the same caller returns the original response rather than creating a second offer. Other mutating endpoints are not de-duplicated — retry them only when you know it is safe.

Endpoint groups

Endpoints are organized into the following groups:

• API
• Auditing
• Buyer
• Contact
• Cosell
• Entitlement
• Knowledge Search
• Metering
• Notification
• Offer
• OfferSet
• Operation
• Organization
• Product
• Report
• Revenue
• Support

Using the reference

Explore every endpoint in the interactive reference below. Each operation also has a static page at /api/<operation>/ and a Markdown version at /api/<operation>.md for agents and LLMs.