Skip to main content
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

NameTypeRequiredDescription
owner_namestringYesUsername of the project owner (path parameter)
namestringNoFilter by project name (query parameter)
orderingstringNoField to order results by (query parameter)
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)

​
Request

curl "https://server.avala.ai/api/v1/projects/johndoe/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "next": null,
  "previous": null,
  "results": [
    {
      "uid": "770a9600-g40d-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

FieldTypeDescription
uidstring (UUID)Unique identifier for the project
namestringProject name (1-100 characters)
task_typestringType of annotation task assigned to this project
statusstringCurrent project status
is_activebooleanWhether the project is currently active
visibilitystringpublic or private
is_importedbooleanWhether the project was imported from an external source
owner_namestringUsername of the project owner
short_descriptionstringBrief description of the project
industry_iconstringIndustry category icon identifier

​
Task Types

TypeDescription
image-annotation2D image annotation (bounding boxes, polygons, segmentation)
video-annotationVideo frame-by-frame annotation
point-cloud-annotation3D point cloud annotation with cuboids
point-cloud-objects3D object detection in point clouds

​
Project Statuses

StatusDescription
pending-approvalAwaiting approval to start
activeCurrently active and accepting annotations
pausedTemporarily paused
canceledCanceled and no longer active
archivedArchived for historical reference
completedAll annotation tasks have been completed

​
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.