API
Use OpenAPI and direct HTTP when you need machine-readable contracts.
Use direct HTTP as an escape hatch when the SDK is not suitable or a non-TypeScript service needs a machine-readable contract. Shell-capable coding agents should use the CLI so discovery, output, and errors remain machine-stable.
Contract Sources
| Resource | Use for |
|---|---|
/api/openapi | endpoint paths, parameters, auth, responses, examples |
https://api.01.software | production API origin |
/developers/cli.mdx | machine-readable CLI guide for shell-capable agents |
/llms-full.txt | broad human-readable context for AI tools |
/api/search | targeted docs search |
Authentication
- Browser reads use Publishable Key and allowed origins.
- Server writes require trusted server credentials.
- User-scoped operations should stay tied to the current human user.
- Agent CLI credentials use the same trusted secret boundary as server SDK work.
- Hosted MCP is limited to read-only discovery; OpenAPI remains the direct HTTP contract.
Public Read Caching and Fresh Reads
Some collection GET responses read with a Publishable Key and no authentication are cached by the CDN.
Changes saved in Console may not appear immediately in public read responses.
The CDN can return a previous response while refreshing the cache; delayed or failed invalidation can defer visibility until cache expiry and revalidation.
Requests with an Authorization header or the Payload session cookie (payload-token) bypass this CDN cache.
Authentication and access checks still apply.
To avoid a previous CDN response immediately after a change, read from a trusted server using a Secret Key with read permission.
Use the server SDK client or send both X-Publishable-Key and Authorization: Bearer <Secret Key> in a direct HTTP request.
Keep the Secret Key within the server boundary and refresh any query cache in your application separately.
API Request Rate Limits
Publishable Key requests share per-minute and per-hour limits by the workspace that owns the key. These are the current operating plans’ Live limits, separate from monthly API allowances and proposed plan changes.
| Current plan | Requests per minute | Requests per hour |
|---|---|---|
| Free | 600 | 10,000 |
| Starter | 1,200 | 30,000 |
| Basic | 3,000 | 100,000 |
| Pro | 6,000 | 200,000 |
| Enterprise | Check the applicable agreement and project entitlement | Check the applicable agreement and project entitlement |
Sandbox applies the stricter of the plan limit and 300 requests per minute / 3,000 per hour. Monthly API usage is counted separately. These limits are not usage prices or a promise of unlimited access. Protected paths such as login also have separate limits.
A request rejected by this rate limiter returns 429 with rate_limit_exceeded.
Wait for the response’s Retry-After interval in seconds before retrying.
X-RateLimit-Limit and X-RateLimit-Window (minute or hour) identify the limit.
Response Handling
- Treat validation errors as product copy inputs, not raw customer messages.
- Log request identifiers and status categories without logging secrets.
- Keep retries bounded and idempotent where possible.
Prefer the SDK when it fits the project. Use direct HTTP for service-to-service, generated-client, or non-TypeScript integration needs.
Generated coverage and limits
Use /api/openapi to check supported HTTP methods and paths, request bodies, responses and authentication requirements. It includes Commerce, customer authentication, membership, Events, customer groups, external-effect claims, installation credentials and external customer links.
Generic Payload failures use errors[]. Task-specific endpoints use an error/reason/requestId response, while some paths retain legacy code responses. Check each endpoint’s documented request, response and error formats separately from generic collection operations.
The Ecommerce SDK catalog example maps to the generated GET /api/products/detail/catalog operation, Publishable Key security and ProductDetailCatalog success body. Cart server credential variants share the canonical cart paths. Checkout creation uses POST /api/orders/checkout, detail uses POST /api/checkouts/detail, and server query uses POST /api/checkouts/query. The former cart /server/* and checkout /create, /retrieve, /server/* aliases are not supported transports.
Excluded shaped operations
Community detail, Gallery storefront, Video playback and embedded-admin configuration are excluded from the generated OpenAPI contract. Their SDK or integration guides do not imply OpenAPI coverage; use the owning reference for those capabilities. Check those references for their request and response formats separately from generic collection paths. Coverage does not promise that every SDK helper has a separate HTTP operation.
Credential-specific request, response and security differences on a shared path appear in x-credential-variants. Check whether your client generator consumes that extension. Internal operator sessions are not a public integration authentication scheme. Collection CRUD and other proxy-level transport failures are not exhaustively modeled; do not infer a complete failure catalog from the listed responses.