Slices - Avala Documentation

Create, list, retrieve, and manage slices for your datasets.

Slices are curated subsets of one or more datasets. Each slice is composed of sub-slices that can reference entire datasets, specific items within a dataset, or a filter expression. Slices do not duplicate the underlying data — they reference items in their source datasets.

List Slices

GET /api/v1/slices/{owner}/list/

Returns all slices owned by the specified organization or user.

Parameters

Name	Type	Required	Description
`owner`	string	Yes	Organization slug or username (path parameter)
`ordering`	string	No	Field to order results by (query parameter)
`page`	integer	No	Page number for pagination (query parameter)
`limit`	integer	No	Number of results per page (query parameter)

Request

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

import requests

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

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

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

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

Response

{
  "count": 12,
  "next": "https://api.avala.ai/api/v1/slices/acme-ai/list/?page=2",
  "previous": null,
  "results": [
    {
      "name": "Night Driving Scenes",
      "slug": "night-driving-scenes",
      "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "owner_name": "acme-ai",
      "organization": null,
      "visibility": "private",
      "sub_slices": [
        {
          "type": "dataset",
          "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "source_data": [
        {
          "type": "dataset",
          "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "status": "created",
      "featured_slice_item_urls": [
        "https://cdn.avala.ai/items/abc123.jpg",
        "https://cdn.avala.ai/items/def456.jpg"
      ],
      "item_count": 340
    }
  ]
}

Fields

Field	Type	Description
`name`	string	Display name of the slice
`slug`	string	URL-friendly identifier
`uid`	string (UUID)	Unique identifier for the slice
`owner_name`	string	Username of the slice owner
`organization`	object \| null	Organization the slice belongs to, if any
`visibility`	string	`"public"` or `"private"`
`sub_slices`	array	Sub-slice definitions (see Sub-slice types)
`source_data`	array \| null	Stored sub-slice data used to generate the slice
`status`	string	`"pending"`, `"created"`, or `"failed"`
`featured_slice_item_urls`	array	URLs of up to 4 preview items
`item_count`	integer	Number of items in the slice

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 from one or more sub-slice definitions.

Parameters

Name	Type	Required	Description
`name`	string	Yes	Display name for the slice (1-100 characters)
`visibility`	string	Yes	`"public"` or `"private"`
`sub_slices`	array	Yes	Array of sub-slice objects (see Sub-slice types)
`organization`	object	No	Organization to assign the slice to
`random_selection_count`	integer	No	Randomly select this many items from the sub-slice sources

Request

curl -X POST "https://api.avala.ai/api/v1/slices/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Night Driving Scenes",
    "visibility": "private",
    "sub_slices": [
      {
        "type": "dataset",
        "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
      }
    ]
  }'

import requests

response = requests.post(
    "https://api.avala.ai/api/v1/slices/",
    headers={
        "X-Avala-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json"
    },
    json={
        "name": "Night Driving Scenes",
        "visibility": "private",
        "sub_slices": [
            {
                "type": "dataset",
                "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
            }
        ]
    }
)
slice_data = response.json()

const response = await fetch(
  "https://api.avala.ai/api/v1/slices/",
  {
    method: "POST",
    headers: {
      "X-Avala-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: "Night Driving Scenes",
      visibility: "private",
      sub_slices: [
        {
          type: "dataset",
          dataset_uid: "550e8400-e29b-41d4-a716-446655440000",
        },
      ],
    }),
  }
);
const sliceData = await response.json();

body := strings.NewReader(`{
    "name": "Night Driving Scenes",
    "visibility": "private",
    "sub_slices": [
        {
            "type": "dataset",
            "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
        }
    ]
}`)

req, _ := http.NewRequest("POST", "https://api.avala.ai/api/v1/slices/", body)
req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")
req.Header.Set("Content-Type", "application/json")

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

Response

{
  "name": "Night Driving Scenes",
  "slug": "night-driving-scenes",
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "owner_name": "acme-ai",
  "organization": null,
  "visibility": "private",
  "sub_slices": [
    {
      "type": "dataset",
      "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "source_data": [
    {
      "type": "dataset",
      "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "status": "pending",
  "featured_slice_item_urls": [],
  "item_count": 0
}

Newly created slices have status: "pending" and item_count: 0. Items are populated asynchronously — poll the Get Slice endpoint to check when status changes to "created".

Get Slice

GET /api/v1/slices/{owner}/{slug}/

Returns the details of a specific slice.

Parameters

Name	Type	Required	Description
`owner`	string	Yes	Organization slug or username (path parameter)
`slug`	string	Yes	Slice slug (path parameter)

Request

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

import requests

response = requests.get(
    "https://api.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/",
    headers={"X-Avala-Api-Key": "YOUR_API_KEY"}
)
slice_data = response.json()

const response = await fetch(
  "https://api.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/",
  {
    headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
  }
);
const sliceData = await response.json();

req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/", nil)
req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

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

Response

{
  "name": "Night Driving Scenes",
  "slug": "night-driving-scenes",
  "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "owner_name": "acme-ai",
  "organization": null,
  "visibility": "private",
  "sub_slices": [
    {
      "type": "dataset",
      "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "source_data": [
    {
      "type": "dataset",
      "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "status": "created",
  "featured_slice_item_urls": [
    "https://cdn.avala.ai/items/abc123.jpg",
    "https://cdn.avala.ai/items/def456.jpg",
    "https://cdn.avala.ai/items/ghi789.jpg",
    "https://cdn.avala.ai/items/jkl012.jpg"
  ],
  "item_count": 340
}

Fields

Same as List Slices fields.

List Slice Items

GET /api/v1/slices/{owner}/{slug}/items/list/

Returns the items belonging to a specific slice.

Parameters

Name	Type	Required	Description
`owner`	string	Yes	Organization slug or username (path parameter)
`slug`	string	Yes	Slice slug (path 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/slices/acme-ai/night-driving-scenes/items/list/" \
  -H "X-Avala-Api-Key: $AVALA_API_KEY"

import requests

response = requests.get(
    "https://api.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/items/list/",
    headers={"X-Avala-Api-Key": "YOUR_API_KEY"}
)
items = response.json()["results"]

const response = await fetch(
  "https://api.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/items/list/",
  {
    headers: { "X-Avala-Api-Key": "YOUR_API_KEY" },
  }
);
const { results } = await response.json();

req, _ := http.NewRequest("GET", "https://api.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/items/list/", nil)
req.Header.Set("X-Avala-Api-Key", "YOUR_API_KEY")

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

Response

The response returns dataset items in the same format as List Items. Each item includes uid, key, url, thumbnails, metadata, created_at, and related fields.

Sub-slice Types

Each entry in the sub_slices array has a type field and type-specific properties:

`dataset` — All items from a dataset

Include every item from a dataset.

{
  "type": "dataset",
  "dataset_uid": "550e8400-e29b-41d4-a716-446655440000"
}

Field	Type	Required	Description
`type`	string	Yes	Must be `"dataset"`
`dataset_uid`	string (UUID)	Yes	UID of the source dataset

`dataset_items` — Specific items from a dataset

Include only the specified items.

{
  "type": "dataset_items",
  "dataset_uid": "550e8400-e29b-41d4-a716-446655440000",
  "dataset_item_uids": [
    "11111111-1111-1111-1111-111111111111",
    "22222222-2222-2222-2222-222222222222"
  ]
}

Field	Type	Required	Description
`type`	string	Yes	Must be `"dataset_items"`
`dataset_uid`	string (UUID)	Yes	UID of the source dataset
`dataset_item_uids`	array of UUIDs	Yes	UIDs of items to include

`filters` — Filter expression

Include items matching a filter expression.

{
  "type": "filters",
  "dataset_uid": "550e8400-e29b-41d4-a716-446655440000",
  "filters": {
    "tag": ["night", "rain"]
  }
}

Field	Type	Required	Description
`type`	string	Yes	Must be `"filters"`
`dataset_uid`	string (UUID)	Yes	UID of the source dataset
`filters`	object	Yes	Filter expression object

Validate Slice Name

POST /api/v1/slice/validate/name

Validates a proposed slice name before creation.

Request

curl -X POST "https://api.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"}'

Response

{
  "name": "Night Driving Scenes",
  "isValid": true,
  "message": "Slice slug for name Night Driving Scenes is VALID for user: acme-ai"
}

Field	Type	Description
`name`	string	The name that was validated
`isValid`	boolean	Whether the name is available
`message`	string	Human-readable validation result

Error Responses

Validation Error (400)

{
  "name": ["This field is required."],
  "visibility": ["This field is required."],
  "sub_slices": ["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.

​List Slices

​Parameters

​Request

​Response

​Fields

​Create Slice

​Parameters

​Request

​Response

​Get Slice

​Parameters

​Request

​Response

​Fields

​List Slice Items

​Parameters

​Request

​Response

​Sub-slice Types

​dataset — All items from a dataset

​dataset_items — Specific items from a dataset

​filters — Filter expression

​Validate Slice Name

​Request

​Response

​Error Responses

​Validation Error (400)

​Unauthorized (401)

​Permission Denied (403)

​Not Found (404)

List Slices

Parameters

Request

Response

Fields

Create Slice

Parameters

Request

Response

Get Slice

Parameters

Request

Response

Fields

List Slice Items

Parameters

Request

Response

Sub-slice Types

`dataset` — All items from a dataset

`dataset_items` — Specific items from a dataset

`filters` — Filter expression

Validate Slice Name

Request

Response

Error Responses

Validation Error (400)

Unauthorized (401)

Permission Denied (403)

Not Found (404)