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.
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.