Projects API - Avala Documentation

List and retrieve annotation projects.

List Projects

GET /api/v1/projects/{owner_name}/

Returns all projects belonging to a specific owner that are visible to the authenticated user.

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"

import requests

response = requests.get(
    "https://api.avala.ai/api/v1/projects/johndoe/",
    headers={"X-Avala-Api-Key": "YOUR_API_KEY"}
)
projects = response.json()["results"]

const response = await fetch(
  "https://api.avala.ai/api/v1/projects/johndoe/",
  {
    headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
  }
);
const { results } = await response.json();

req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/projects/johndoe/", nil)
req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

resp, err := http.DefaultClient.Do(req)

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/

Create a new project by cloning an existing template project onto a new dataset. The new project inherits the template’s task definitions, annotation configuration, and industry settings. The project is created in 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"
  }'

import requests

response = requests.post(
    "https://api.avala.ai/api/v1/projects/create-from-existing/",
    headers={"X-Avala-Api-Key": "YOUR_API_KEY"},
    json={
        "source_project_uid": "770a9600-a40d-63f6-c938-668877660000",
        "name": "Batch 2026-04-09",
        "image_dataset_uid": "880b0700-b51e-74g7-d049-779988770000",
    },
)
project = response.json()

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/

Approve a project to start annotation work. This triggers the full task creation pipeline: tasks, work units, and work batches are created automatically. Coworkers can then claim and annotate the tasks.

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"

import requests

response = requests.post(
    "https://api.avala.ai/api/v1/projects/990c1800-c62f-85h8-e150-880099880000/approve/",
    headers={"X-Avala-Api-Key": "YOUR_API_KEY"},
)
project = response.json()
print(f"Project {project['name']} is now {project['status']}")

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}/

Change a project’s status. Available actions depend on the current status.

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 = requests.post(
    "https://api.avala.ai/api/v1/projects/990c1800-c62f-85h8-e150-880099880000/pause/",
    headers={"X-Avala-Api-Key": "YOUR_API_KEY"},
)

Response

Returns the updated project object (same shape as the approve response).

Error Responses

Not Found (404)

{
  "detail": "Not found."
}

Returned when the specified owner does not exist or has no visible projects.

Permission Denied (403)

{
  "detail": "You do not have permission to perform this action."
}

Returned when the authenticated user does not have access to the requested projects.

Unauthorized (401)

{
  "detail": "Invalid API key."
}

Returned when the X-Avala-Api-Key header is missing or contains an invalid key.

​List Projects

​Parameters

​Request

​Response

​Fields

​Task Types

​Project Statuses

​Clone Project from Template

​Request Body

​Request

​Response

​Approve Project

​Requirements

​Parameters

​Request

​Response

​Error Responses

​Pause / Resume / Cancel / Archive Project

​Request

​Response

​Error Responses

​Not Found (404)

​Permission Denied (403)

​Unauthorized (401)

List Projects

Parameters

Request

Response

Fields

Task Types

Project Statuses

Clone Project from Template

Request Body

Request

Response

Approve Project

Requirements

Parameters

Request

Response

Error Responses

Pause / Resume / Cancel / Archive Project

Request

Response

Error Responses

Not Found (404)

Permission Denied (403)

Unauthorized (401)