API
Use OpenAPI and direct HTTP when you need machine-readable contracts.
API
Use direct HTTP when the SDK is not suitable, when a non-TypeScript service needs integration, or when an AI/tooling system needs a machine-readable contract.
Contract Sources
| Resource | Use for |
|---|---|
/api/openapi | endpoint paths, parameters, auth, responses, examples |
https://api.01.software | production API origin |
/llms-full.txt | 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.
- MCP and OpenAPI are complementary: MCP is for approved agent context, OpenAPI is the 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.