Reference
API overview
Auth, idempotency, pagination.
Clipie's public API lives under https://api.clipie.ai/v1/*. During beta we expose the same routes at https://api-dev.clipie.ai/.
Auth
Send Authorization: Bearer <jwt> on every request. The JWT is an RS256-signed access token issued from/auth/sign-in or /auth/oauth/{provider} and expires in 15 minutes β rotate via /auth/refresh.
Workspace scoping
Most write endpoints require an X-Workspace-Id header to disambiguate which workspace the call operates on. The signed-in user must be a member of that workspace.
Idempotency
Pass Idempotency-Key: <uuid> on any write endpoint to make retries safe. We dedupe for 7 days per key.
Pagination
Cursor-based β pass ?cursor=<prev_next_cursor>&limit=N. Each response returns next_cursor which is null at the end.
Errors
Always JSON: { "detail": { "code": "β¦", "message": "β¦" } }. HTTP status follows conventions (400 validation, 401 auth, 402 insufficient credits, 403 forbidden, 404 not found, 429 rate-limit).