API
Use OpenAPI and direct HTTP when you need machine-readable contracts.
API
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.
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
/api/openapi serves the current generated contract. Generic paths derive from SDK collection buckets; shaped operations derive their method/path identities from the shared HTTP manifest. The generated contract includes Commerce, customer authentication, membership, Events, customer groups, external-effect claims, installation credentials and external customer links. Generic Payload failures keep errors[]; shaped endpoints have their own error/reason/requestId envelope, with retained legacy code responses on some paths. Do not infer a DTO or error shape from a generic collection operation.
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. Generic collection paths do not describe these excluded shaped DTOs. 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.