Skip to Content

REST APIs

The app API and provider-compatible gateway are separate HTTP surfaces. The app hosts /api/client and /api/admin; inference uses the gateway’s /v1 base URL. Use the URLs selected for your deployment, not an app API URL as a gateway URL.

Customer authentication

Identify a customer by sending its configured identity provider’s JWT as jwtToken:

curl "$MODEM_APP_URL/api/client/projects/$PROJECT_ID/identify" \ -H 'Content-Type: application/json' \ --data-binary @identity-request.json

identity-request.json contains { "jwtToken": "IDENTITY_PROVIDER_TOKEN" }. The result supplies the customer session. Treat this file and the returned access/refresh tokens as credentials; placeholders here are not real keys.

For subsequent addressed customer calls, send Authorization: Bearer CUSTOMER_ACCESS_TOKEN:

curl "$MODEM_APP_URL/api/client/projects/$PROJECT_ID/customers/$CUSTOMER_ID/usage" \ -H "Authorization: Bearer $CUSTOMER_ACCESS_TOKEN"

The token must belong to the addressed customer and project. A synthetic Sandbox customer can instead use Authorization: Sandbox SANDBOX_SECRET on routes that include its customer ID. It is not a substitute for an identity token or an unaddressed refresh flow. Refresh takes { "refreshToken": "CUSTOMER_REFRESH_TOKEN" } at POST /api/client/refresh.

See customer authentication, App Store purchases and checkout for complete session and payment flows.

Errors

App API failures have an HTTP status and a JSON body:

{ "success": false, "error": { "code": "FORBIDDEN", "message": "The key cannot perform this operation", "requestId": "REQUEST_ID", "requiredPermission": "customers:write" } }

reason, param and requiredPermission appear only where relevant. Preserve requestId for diagnosis. Retry-After is present only when the server supplies a useful delay; do not assume every 429 includes it. An unreachable server, bad response body or lost response is different from a confirmed server refusal.

The gateway uses provider-compatible error formats instead of this app envelope. Follow gateway errors for inference. SDK callers should use the exported error guards rather than parse message text.

Customer endpoints

JSON request and response schemas are exported by @preternatural-js/api-schema/client. The client SDK also exports its generated OpenAPI document as @preternatural-js/client-sdk/docs/openapi.json.

The customer HTTP reference lists the SDK transport operations with their request and response schemas.

Additional customer routes not represented by those SDK transport methods:

Method and pathPurpose
GET /api/client/projects/{project_id}/customers/{customer_id}Read the authenticated customer’s resource.
POST /api/client/projects/{project_id}/freeRead the authenticated customer’s rate-limit allowances.
GET /api/client/projects/{project_id}/oauth/github/authorizeBegin hosted GitHub authorization with return URL, state and PKCE parameters.
GET /api/client/oauth/github/callbackProvider redirect handler; use the authorization flow rather than calling this as an application endpoint.

The upload-receipt operation accepts the supported StoreKit 1, StoreKit 2 and consumable inputs described in App Store purchases. Its schema is available through the transport export; there is no high-level client.receipts resource.

GitHub sign-in refusals

Hosted GitHub sign-in has separate hourly budgets for the project and caller address. The current implementation permits 100 starts per project and 20 per address per hour. On Vercel it uses the trusted platform address header; deployments without that trusted address source share the unattributed-address budget. These are sign-in protection budgets, not a customer’s inference rate rules.

Exhausting a budget refuses a new authorization attempt; an unavailable limiter store also refuses sign-in rather than pretending authorization succeeded. Wait for the reported delay when present and diagnose server availability separately from a GitHub rejection. Do not clear an otherwise valid customer session solely because starting a new OAuth flow failed.

Admin authentication

Send the admin API key as Authorization: Bearer MODEM_ADMIN_API_KEY. The key’s permissions, project selection and allowed modes all apply. API keys and permissions explains these grants. A full key still cannot call a session-only operation.

Ordinary resource routes accept the authorized owner session or a suitably scoped key. Authenticating key routes require the current key itself. Browser session only routes cannot be automated by sending another key. Workspace resources need All projects in both modes. Creating a project requires All projects and access to the requested mode.

Admin list resources that expose limit and startingAfter use the API list envelope; pass the last returned ID as the next startingAfter cursor when hasMore is true. Do not apply that pagination pattern to SDK methods documented as returning a complete array.

Admin endpoints

The admin endpoint permission inventory is generated directly from the shared authorization table, including session-only and authenticating-key operations. JSON schemas and operation IDs are in the admin HTTP reference; resource workflows explain how to combine them.

Rule retrieval/deletion and collection deletion are available over REST even where the high-level SDK only exposes list/create/update. Backup planning, configuration import and provider lifecycle actions also have distinct behavior: use their workflow guides rather than treating every POST as a freely repeatable mutation.

App-internal /api/dashboard and replication routes are not a second supported admin API. Integrate through the public client/admin endpoints and SDKs instead.

Request and response reference

Use the rendered customer HTTP reference and admin HTTP reference for operation parameters, request bodies and response schemas. Download the corresponding customer OpenAPI document or admin OpenAPI document for tooling.

The exported specifications describe the operations they contain. Additional session and provider callback routes described here and in the permission inventory are explained by their workflow guides; they are not silently added to the exported schema. Shared authentication and error conventions on this page also apply where an operation’s specification omits those declarations.

Last updated on