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

# Slices

> API reference for data slicing

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

<Tip>
  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.
</Tip>

## 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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/slices/acme-ai/list/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  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"]
  ```

  ```typescript TypeScript theme={null}
  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();
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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](#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](#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

<CodeGroup>
  ```bash cURL theme={null}
  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"
        }
      ]
    }'
  ```

  ```python Python theme={null}
  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()
  ```

  ```typescript TypeScript theme={null}
  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();
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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
}
```

<Tip>
  Newly created slices have `status: "pending"` and `item_count: 0`. Items are populated asynchronously — poll the [Get Slice](#get-slice) endpoint to check when `status` changes to `"created"`.
</Tip>

***

## 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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  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()
  ```

  ```typescript TypeScript theme={null}
  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();
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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](#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

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.avala.ai/api/v1/slices/acme-ai/night-driving-scenes/items/list/" \
    -H "X-Avala-Api-Key: $AVALA_API_KEY"
  ```

  ```python Python theme={null}
  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"]
  ```

  ```typescript TypeScript theme={null}
  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();
  ```

  ```go Go theme={null}
  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)
  ```
</CodeGroup>

### Response

The response returns dataset items in the same format as [List Items](/docs/api-reference/dataset-items#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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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

<CodeGroup>
  ```bash cURL theme={null}
  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"}'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "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)

```json theme={null}
{
  "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)

```json theme={null}
{
  "detail": "Invalid API key."
}
```

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

### Permission Denied (403)

```json theme={null}
{
  "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)

```json theme={null}
{
  "detail": "Not found."
}
```

Returned when the specified slice or referenced dataset UUID does not exist.