Zudo WorksAPI conventions
| Topic | Convention |
|---|---|
| Base URL | https://api.zudoworks.com/api/v1 (self-hosted: <your origin>/api/v1) |
| Authentication | Session cookie (the web app, after POST /auth/login) or API key: Authorization: Bearer zk_… (scopes = permission keys, or *) |
| Tenant | Always the caller's own workspace, resolved from the session or key. Never sent in headers, queries or bodies (a tenant_id in a body is a 400). |
| Content type | application/json (strict schemas: unknown keys are rejected). Uploads use multipart/form-data. |
| Ids | UUIDs. Forms also accept their slug on GET /forms/:id. |
| Codes | Upper-case, ^[A-Z0-9][A-Z0-9._/-]{0,63}$; normalised server-side. |
| Quantities & money | Decimal strings (e.g. "12.500", "1250.00"), never floats. |
| Dates | YYYY-MM-DD for dates; ISO 8601 UTC for timestamps. |
| Lists | page, page_size (≤ 200), search, filters and sort as documented per endpoint; paged responses are { items, total, page, page_size }. |
| Idempotency | Posting movements, job issues / returns and PO receipts take an idempotency_key; the same key replays the original result. |
| Rate limits | 600 requests / minute per IP (API-wide); sign-in and signup have their own throttles; API-key calls count against the plan's monthly quota. |
| Errors | { "error": { "code": "<snake_case>", "message": "<human text>", "details": [ { … } ] } } — see §42 |
| Audit | Every write is recorded (actor, action, entity, summary, metadata). |
Permissions in brackets below are required; [public] needs no session; [super-admin] needs a super-admin session.
Last updated