Embedded self-service API

Clients use the short-lived Bearer token returned by token exchange with /api/v1/apps/{app}/users/me/* under a fixed Application. Never let a client submit an arbitrary user ID, and never use an AppClient secret for these requests.

Capability	Method and path
Current entitlements	GET /api/v1/apps/{app}/users/me/entitlements
Balance	GET /api/v1/apps/{app}/users/me/wallet
Transactions	GET /api/v1/apps/{app}/users/me/transactions
Usage	GET /api/v1/apps/{app}/users/me/usage
Orders	GET/POST /api/v1/apps/{app}/users/me/orders
Personal statements	GET /api/v1/apps/{app}/users/me/statements
Support tickets	/api/v1/apps/{app}/users/me/support/tickets*

When creating an order, reuse one UUID Idempotency-Key for the same business operation. A returned payment intent is not proof of payment; use the subsequently queried order status as the final result.

Cursors are opaque. Return next_cursor unchanged as cursor and obey has_more. Money, Credits, balances, and rates are decimal strings; preserve server precision for display and use a decimal library for calculations.

With the same short-lived Bearer token, the data API can expose authorized endpoints such as /v1/chat/completions, /v1/balance, and /v1/usage. Available capabilities follow current entitlements and /v1/models.

SDK 0.3.0 additions

createOrder returns a mode of redirect, qr, or client_sdk. The last mode provides client_params (clientParams in Swift/Kotlin) for the payment component. These parameters expire and must not be logged or persisted. Confirm payment through the order status.

Gateway wrappers also cover Responses, Messages, token counting, embeddings, native Gemini generation, and image/video generation. Model protocols must be published and permitted for the current user; see the SDK method table and protocol guide. The SDK does not replace backend payment verification, authorization, or token refresh.