Documentation Index
Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
Use this file to discover all available pages before exploring further.
List and retrieve annotation projects.
List Projects
GET /api/v1/projects/{owner_name}/
Parameters
| Name | Type | Required | Description |
|---|
owner_name | string | Yes | Username of the project owner (path parameter) |
name | string | No | Filter by project name (query parameter) |
ordering | string | No | Field to order results by (query parameter) |
cursor | string | No | Cursor for pagination (query parameter) |
limit | integer | No | Number of results per page (query parameter) |
Request
curl "https://api.avala.ai/api/v1/projects/johndoe/" \
-H "X-Avala-Api-Key: $AVALA_API_KEY"
Response
{
"next": null,
"previous": null,
"results": [
{
"uid": "770a9600-a40d-63f6-c938-668877660000",
"name": "Object Detection",
"task_type": "image-annotation",
"status": "active",
"is_active": true,
"visibility": "private",
"is_imported": false,
"owner_name": "johndoe",
"short_description": "Detect vehicles and pedestrians",
"industry_icon": "automotive"
}
]
}
Fields
| Field | Type | Description |
|---|
uid | string (UUID) | Unique identifier for the project |
name | string | Project name (1-100 characters) |
task_type | string | Type of annotation task assigned to this project |
status | string | Current project status |
is_active | boolean | Whether the project is currently active |
visibility | string | public or private |
is_imported | boolean | Whether the project was imported from an external source |
owner_name | string | Username of the project owner |
short_description | string | Brief description of the project |
industry_icon | string | Industry category icon identifier |
Task Types
| Type | Description |
|---|
image-annotation | 2D image annotation (bounding boxes, polygons, segmentation) |
video-annotation | Video frame-by-frame annotation |
point-cloud-annotation | 3D point cloud annotation with cuboids |
point-cloud-objects | 3D object detection in point clouds |
Project Statuses
| Status | Description |
|---|
pending-approval | Awaiting approval to start |
active | Currently active and accepting annotations |
paused | Temporarily paused |
canceled | Canceled and no longer active |
archived | Archived for historical reference |
completed | All annotation tasks have been completed |
Clone Project from Template
POST /api/v1/projects/create-from-existing/
pending-approval status.
Requires IsCustomer or IsStaff permission. Coworker accounts cannot clone projects.
Request Body
| Name | Type | Required | Description |
|---|
source_project_uid | string (UUID) | Yes | UID of the template project to clone |
name | string | Yes | Name for the new project (must be unique per owner) |
image_dataset_uid | string (UUID) | No | UID of the image dataset to attach |
lidar_dataset_uid | string (UUID) | No | UID of the LiDAR dataset (for 3D projects) |
slice_uid | string (UUID) | No | UID of a slice to attach instead of a full dataset |
copy_collaborators | boolean | No | Copy collaborators from the template (default: true) |
Request
curl -X POST "https://api.avala.ai/api/v1/projects/create-from-existing/" \
-H "X-Avala-Api-Key: $AVALA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_project_uid": "770a9600-a40d-63f6-c938-668877660000",
"name": "Batch 2026-04-09",
"image_dataset_uid": "880b0700-b51e-74g7-d049-779988770000"
}'
Response
{
"uid": "990c1800-c62f-85h8-e150-880099880000",
"name": "Batch 2026-04-09",
"status": "pending-approval",
"task_type": "image-annotation",
"owner_name": "dev@acme.com",
"visibility": "private"
}
Approve Project
POST /api/v1/projects/{uid}/approve/
Approving a project starts billable annotation work. This action cannot be undone — use pause or cancel to stop work after approval.
Requirements
- Plan: Your organization must be on the PRO or ENTERPRISE plan. BASIC plan organizations receive a
403 error.
- Scope: API keys must include the
projects.write scope.
- Ownership: You must own the project (or be staff).
- Status: The project must be in
pending-approval status.
Parameters
| Name | Type | Required | Description |
|---|
uid | string (UUID) | Yes | Project UID (path parameter) |
Request
curl -X POST "https://api.avala.ai/api/v1/projects/990c1800-c62f-85h8-e150-880099880000/approve/" \
-H "X-Avala-Api-Key: $AVALA_API_KEY"
Response
{
"uid": "990c1800-c62f-85h8-e150-880099880000",
"name": "Batch 2026-04-09",
"status": "active",
"task_type": "image-annotation",
"owner_name": "dev@acme.com",
"visibility": "private"
}
Error Responses
| Status | Code | Description |
|---|
403 | plan_insufficient | Organization is on BASIC plan. Upgrade to PRO or ENTERPRISE. |
403 | scope_required | API key is missing the projects.write scope. |
400 | — | Project is not in pending-approval status (invalid state transition). |
404 | — | Project not found or not owned by the authenticated user. |
{
"detail": "Project approval requires a PRO or ENTERPRISE plan.",
"code": "plan_insufficient",
"doc_url": "https://docs.avala.ai/api/errors#plan_insufficient"
}
Pause / Resume / Cancel / Archive Project
POST /api/v1/projects/{uid}/{action}/
| Action | From Status | To Status | Description |
|---|
pause | active | paused | Temporarily stop annotation work |
resume | paused | active | Resume paused annotation work |
cancel | active, paused | canceled | Permanently stop annotation work |
archive | completed, canceled | archived | Archive for historical reference |
Pause, resume, cancel, and archive do not require specific API key scopes. Only the approve action requires the projects.write scope.
Request
curl -X POST "https://api.avala.ai/api/v1/projects/990c1800-c62f-85h8-e150-880099880000/pause/" \
-H "X-Avala-Api-Key: $AVALA_API_KEY"
Response
Returns the updated project object (same shape as the approve response).
Error Responses
Not Found (404)
{
"detail": "Not found."
}
Permission Denied (403)
{
"detail": "You do not have permission to perform this action."
}
Unauthorized (401)
{
"detail": "Invalid API key."
}
X-Avala-Api-Key header is missing or contains an invalid key.
