API reference
JSON over HTTPS. Predictable resources, cursor pagination, idempotency keys, and stable error codes.
Base URL
// base-urltext
https://api.allo.io/v1
Resources
| Resource | Description |
|---|
| /canvases | Canvases hold blocks. The unit of work in ALLO. |
| /canvases/:id/blocks | Blocks on a canvas. Image, file, embed, text, frame. |
| /projects | Project rows. Status, members, linked canvases. |
| /comments | Threaded comments pinned to blocks or coordinates. |
| /goals | OKR style goals with progress and linked work. |
| /members | Workspace members and guests. |
| /webhooks | Subscribe to events. |
List endpoints return up to 100 items per page. Pass cursor to advance.
// paginate.tsTypeScript
let cursor
do {
const page = await allo.projects.list({ cursor, limit: 100 })
cursor = page.next_cursor
} while (cursor)Idempotency
Pass an Idempotency-Key header on POST requests to safely retry. Duplicate requests with the same key return the original response.
Errors
Errors carry a stable code, a human message, a docs link, and a request_id.
// error.jsonJSON
{
"error": {
"code": "canvas_block_too_large",
"message": "Block exceeds 50 MB upload limit.",
"doc_url": "https://docs.allo.io/errors/blocks",
"request_id": "req_01HE2VK..."
}
}Status codes
| Code | Meaning |
|---|
| 200 | OK |
| 201 | Created |
| 400 | Validation error. See error.code. |
| 401 | Missing or invalid auth. |
| 403 | Token lacks required scope. |
| 404 | Resource not found. |
| 409 | Idempotency conflict or stale write. |
| 429 | Rate limited. See Retry-After header. |
| 500 | Server error. Safe to retry with backoff. |
Rate limits
600 requests per minute per workspace by default. Bursts up to 1,000 are absorbed. Higher limits on Enterprise.
// INFO · Retry-After
When you receive 429, wait Retry-After seconds before retrying. The SDK does this automatically.