Skip to main content
Create, list, retrieve, and delete slices for your datasets.
Slices are filtered subsets of datasets. Use them to isolate specific portions of your data for targeted exports, focused quality control reviews, or scoped annotation workflows. A slice references items in its parent dataset via a filter query — it does not duplicate the underlying data.

​
List Slices

GET /api/v1/slices/{owner}/list/
Returns all slices owned by the specified organization or user.

​
Parameters

NameTypeRequiredDescription
ownerstringYesOrganization slug or username (path 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/slices/acme-ai/list/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "count": 12,
  "next": "https://server.avala.ai/api/v1/slices/acme-ai/list/?cursor=cD0yMDI1...",
  "previous": null,
  "results": [
    {
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Night Driving Scenes",
      "slug": "night-driving-scenes",
      "description": "Images captured in low-light driving conditions",
      "item_count": 340,
      "created_at": "2025-03-15T08:30:00Z",
      "updated_at": "2025-03-16T12:00:00Z"
    }
  ]
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the slice
namestringDisplay name of the slice
slugstringURL-friendly identifier for the slice
descriptionstringHuman-readable description of the slice
item_countintegerNumber of items matched by the filter query
created_atstring (datetime)ISO 8601 timestamp of when the slice was created
updated_atstring (datetime)ISO 8601 timestamp of when the slice was last updated
You can also list slices filtered by dataset: 
GET /api/v1/slices/dataset/{dataset_uid}/

​
Create Slice

POST /api/v1/slices/
Creates a new slice for a dataset.

​
Parameters

NameTypeRequiredDescription
namestringYesDisplay name for the slice (1-255 characters)
datasetstring (UUID)YesUUID of the parent dataset
descriptionstringNoHuman-readable description of the slice

​
Request

curl -X POST "https://server.avala.ai/api/v1/slices/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Night Driving Scenes",
    "dataset": "550e8400-e29b-41d4-a716-446655440000",
    "description": "Images captured in low-light driving conditions"
  }'

​
Response

{
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Night Driving Scenes",
  "slug": "night-driving-scenes",
  "description": "Images captured in low-light driving conditions",
  "item_count": 0,
  "created_at": "2025-03-15T08:30:00Z",
  "updated_at": "2025-03-15T08:30:00Z"
}

​
Get Slice

GET /api/v1/slices/{owner}/{slug}/
Returns the details of a specific slice.

​
Parameters

NameTypeRequiredDescription
ownerstringYesOrganization slug or username (path parameter)
slugstringYesSlice slug (path parameter)

​
Request

curl "https://server.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Response

{
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Night Driving Scenes",
  "slug": "night-driving-scenes",
  "description": "Images captured in low-light driving conditions",
  "item_count": 340,
  "created_at": "2025-03-15T08:30:00Z",
  "updated_at": "2025-03-16T12:00:00Z"
}

​
Fields

FieldTypeDescription
uidstring (UUID)Unique identifier for the slice
namestringDisplay name of the slice
slugstringURL-friendly identifier for the slice
descriptionstringHuman-readable description of the slice
item_countintegerNumber of items matched by the filter query
created_atstring (datetime)ISO 8601 timestamp of when the slice was created
updated_atstring (datetime)ISO 8601 timestamp of when the slice was last updated

​
List Slice Items

GET /api/v1/slices/{owner}/{slug}/items/list/
Returns the items belonging to a specific slice.

​
Parameters

NameTypeRequiredDescription
ownerstringYesOrganization slug or username (path parameter)
slugstringYesSlice slug (path parameter)
cursorstringNoCursor for pagination (query parameter)
limitintegerNoNumber of results per page (query parameter)

​
Request

curl "https://server.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/items/list/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

​
Validate Slice Name

POST /api/v1/slice/validate/name
Validates a proposed slice name before creation.

​
Request

curl -X POST "https://server.avala.ai/api/v1/slice/validate/name" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Night Driving Scenes"}'

​
Error Responses

​
Validation Error (400)

{
  "name": ["This field is required."],
  "dataset": ["This field is required."]
}
Returned when the request body is missing required fields or contains invalid values.

​
Unauthorized (401)

{
  "detail": "Invalid API key."
}
Returned when the X-Avala-Api-Key header is missing or contains an invalid key.

​
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 dataset or slice.

​
Not Found (404)

{
  "detail": "Not found."
}
Returned when the specified slice or referenced dataset UUID does not exist.