> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akhara.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Company name is Akhara AI (never Rubric AI). Keep lowercase rubric/rubrics only when meaning grading criteria.
> Expert Review (docs path talent/) is enterprise BYO experts for audit and review: invite customer specialists; do not pitch Akhara recruiting or a public expert career portal. RLHF and domain writing are secondary work types.
> Prefer concrete API examples against public hosts: Environments eval API https://agi.akhara.ai, Control plane PDP https://api.akhara.dev, Evaluation https://app.akhara.ai / https://api.akhara.ai, Expert Review portal https://talent.akhara.ai.
> Do not invent a public hostname for private orchestrators or env API internals.
> Do not confuse control-plane latches with Environments confirmation latches.
> Environments SDK/API examples: curl against https://agi.akhara.ai. Evaluation SDK: from akhara import Akhara and AKHARA_API_KEY.
> Start with /llms.txt for the docs index and OpenAPI links; fetch individual pages as .md exports.

# Dataset APIs

> Create, manage, and query datasets containing samples for evaluation.

## Overview

Datasets are collections of samples that you evaluate. Each dataset belongs to a project and contains samples of a specific modality (voice, notes, or imaging).

**Base URL:** `https://api.akhara.ai/v1/datasets`

***

## Create Dataset

Create a new dataset within a project.

<EndpointBlock method="POST" path="/v1/datasets" />

### Request Body

| Parameter     | Type   | Required | Description                         |
| ------------- | ------ | -------- | ----------------------------------- |
| `name`        | string | Yes      | Human-readable name for the dataset |
| `project`     | string | Yes      | Project ID (`proj_xxx`)             |
| `description` | string | No       | Description of the dataset contents |
| `modality`    | string | Yes      | One of: `voice`, `notes`, `imaging` |
| `schema`      | object | No       | Custom schema for sample validation |
| `metadata`    | object | No       | Arbitrary key-value pairs           |

### Example Request

<CodeGroup>
  ```python Python theme={null}
  from akhara import Akhara

  client = Akhara()

  dataset = client.datasets.create(
      name="Q1 Triage Calls",
      project="proj_abc123",
      description="Production triage calls from Q1 2024",
      modality="voice",
      metadata={
          "source": "production",
          "date_range": "2024-01-01 to 2024-03-31"
      }
  )

  print(f"Created dataset: {dataset.id}")
  ```

  ```typescript TypeScript theme={null}
  import Akhara from '@akhara/sdk';

  const client = new Akhara();

  const dataset = await client.datasets.create({
    name: "Q1 Triage Calls",
    project: "proj_abc123",
    description: "Production triage calls from Q1 2024",
    modality: "voice",
    metadata: {
      source: "production",
      date_range: "2024-01-01 to 2024-03-31"
    }
  });

  console.log(`Created dataset: ${dataset.id}`);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.akhara.ai/v1/datasets \
    -H "Authorization: Bearer rb_live_xxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Q1 Triage Calls",
      "project": "proj_abc123",
      "description": "Production triage calls from Q1 2024",
      "modality": "voice",
      "metadata": {
        "source": "production",
        "date_range": "2024-01-01 to 2024-03-31"
      }
    }'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "ds_xyz789",
  "object": "dataset",
  "name": "Q1 Triage Calls",
  "project": "proj_abc123",
  "description": "Production triage calls from Q1 2024",
  "modality": "voice",
  "sample_count": 0,
  "schema": null,
  "metadata": {
    "source": "production",
    "date_range": "2024-01-01 to 2024-03-31"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

***

## List Datasets

Retrieve all datasets in a project or organization.

<EndpointBlock method="GET" path="/v1/datasets" />

### Query Parameters

| Parameter  | Type    | Required | Description                          |
| ---------- | ------- | -------- | ------------------------------------ |
| `project`  | string  | No       | Filter by project ID                 |
| `modality` | string  | No       | Filter by modality                   |
| `limit`    | integer | No       | Results per page (1-100, default 20) |
| `after`    | string  | No       | Cursor for pagination                |

### Example Request

<CodeGroup>
  ```python Python theme={null}
  # List all datasets in a project
  datasets = client.datasets.list(
      project="proj_abc123",
      limit=50
  )

  for ds in datasets:
      print(f"{ds.name}: {ds.sample_count} samples")

  # Paginate through results
  all_datasets = []
  cursor = None
  while True:
      page = client.datasets.list(project="proj_abc123", after=cursor)
      all_datasets.extend(page.data)
      if not page.has_more:
          break
      cursor = page.data[-1].id
  ```

  ```bash cURL theme={null}
  curl "https://api.akhara.ai/v1/datasets?project=proj_abc123&limit=50" \
    -H "Authorization: Bearer rb_live_xxxxxxxx"
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "ds_xyz789",
      "object": "dataset",
      "name": "Q1 Triage Calls",
      "project": "proj_abc123",
      "modality": "voice",
      "sample_count": 1247,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "ds_abc456",
      "object": "dataset",
      "name": "Golden Test Set",
      "project": "proj_abc123",
      "modality": "voice",
      "sample_count": 200,
      "created_at": "2024-01-10T08:00:00Z"
    }
  ],
  "has_more": false
}
```

***

## Get Dataset

Retrieve a specific dataset by ID.

<EndpointBlock method="GET" path="/v1/datasets/{dataset_id}" />

### Path Parameters

| Parameter    | Type   | Required | Description    |
| ------------ | ------ | -------- | -------------- |
| `dataset_id` | string | Yes      | The dataset ID |

### Example Request

<CodeGroup>
  ```python Python theme={null}
  dataset = client.datasets.get("ds_xyz789")

  print(f"Name: {dataset.name}")
  print(f"Samples: {dataset.sample_count}")
  print(f"Modality: {dataset.modality}")
  ```

  ```bash cURL theme={null}
  curl "https://api.akhara.ai/v1/datasets/ds_xyz789" \
    -H "Authorization: Bearer rb_live_xxxxxxxx"
  ```
</CodeGroup>

***

## Update Dataset

Update dataset metadata or configuration.

<EndpointBlock method="PATCH" path="/v1/datasets/{dataset_id}" />

### Request Body

| Parameter     | Type   | Required | Description                             |
| ------------- | ------ | -------- | --------------------------------------- |
| `name`        | string | No       | Updated name                            |
| `description` | string | No       | Updated description                     |
| `metadata`    | object | No       | Updated metadata (merged with existing) |

### Example Request

<CodeGroup>
  ```python Python theme={null}
  dataset = client.datasets.update(
      "ds_xyz789",
      name="Q1 2024 Triage Calls (Final)",
      metadata={"status": "reviewed", "reviewer": "dr.smith"}
  )
  ```

  ```bash cURL theme={null}
  curl -X PATCH "https://api.akhara.ai/v1/datasets/ds_xyz789" \
    -H "Authorization: Bearer rb_live_xxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Q1 2024 Triage Calls (Final)",
      "metadata": {"status": "reviewed"}
    }'
  ```
</CodeGroup>

***

## Delete Dataset

Delete a dataset and all its samples.

<EndpointBlock method="DELETE" path="/v1/datasets/{dataset_id}" />

<Callout type="warning" title="Destructive Action">
  This permanently deletes the dataset and all samples. This action cannot be undone.
</Callout>

### Example Request

<CodeGroup>
  ```python Python theme={null}
  client.datasets.delete("ds_xyz789")
  ```

  ```bash cURL theme={null}
  curl -X DELETE "https://api.akhara.ai/v1/datasets/ds_xyz789" \
    -H "Authorization: Bearer rb_live_xxxxxxxx"
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "ds_xyz789",
  "object": "dataset",
  "deleted": true
}
```

***

## Add Samples

Add samples to a dataset. Supports single or batch upload.

<EndpointBlock method="POST" path="/v1/datasets/{dataset_id}/samples" />

### Request Body

| Parameter | Type  | Required | Description             |
| --------- | ----- | -------- | ----------------------- |
| `samples` | array | Yes      | Array of sample objects |

### Sample Object (Voice)

| Field              | Type   | Required | Description                   |
| ------------------ | ------ | -------- | ----------------------------- |
| `input.transcript` | array  | Yes      | Transcript with speaker turns |
| `input.audio_url`  | string | No       | URL to audio file             |
| `output`           | object | Yes      | AI system output to evaluate  |
| `expected`         | object | No       | Ground truth for comparison   |
| `metadata`         | object | No       | Additional context            |

### Example Request

<CodeGroup>
  ```python Python theme={null}
  # Add single sample
  sample = client.datasets.add_sample(
      dataset="ds_xyz789",
      input={
          "transcript": [
              {"speaker": "agent", "text": "How can I help you today?", "start": 0.0, "end": 2.1},
              {"speaker": "patient", "text": "I have chest pain.", "start": 2.5, "end": 4.2}
          ],
          "audio_url": "s3://bucket/calls/call_123.wav"
      },
      output={
          "triage_level": "urgent",
          "symptoms": ["chest_pain"],
          "recommended_action": "immediate_callback"
      },
      expected={
          "triage_level": "emergent"
      },
      metadata={
          "call_id": "call_123",
          "duration_seconds": 85
      }
  )

  # Batch upload
  samples = client.datasets.add_samples(
      dataset="ds_xyz789",
      samples=[
          {"input": {...}, "output": {...}},
          {"input": {...}, "output": {...}},
          # ... up to 100 samples per batch
      ]
  )
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.akhara.ai/v1/datasets/ds_xyz789/samples" \
    -H "Authorization: Bearer rb_live_xxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "samples": [
        {
          "input": {
            "transcript": [
              {"speaker": "agent", "text": "How can I help?", "start": 0.0, "end": 1.5}
            ]
          },
          "output": {
            "triage_level": "urgent"
          }
        }
      ]
    }'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "id": "smp_abc123",
      "object": "sample",
      "dataset": "ds_xyz789",
      "created_at": "2024-01-15T10:35:00Z"
    }
  ],
  "successful": 1,
  "failed": 0
}
```

***

## List Samples

List samples in a dataset with optional filtering.

<EndpointBlock method="GET" path="/v1/datasets/{dataset_id}/samples" />

### Query Parameters

| Parameter      | Type    | Description                         |
| -------------- | ------- | ----------------------------------- |
| `limit`        | integer | Results per page (1-100)            |
| `after`        | string  | Pagination cursor                   |
| `has_expected` | boolean | Filter to samples with ground truth |
| `metadata`     | object  | Filter by metadata fields           |

### Example Request

<CodeGroup>
  ```python Python theme={null}
  # List samples with ground truth
  samples = client.datasets.list_samples(
      dataset="ds_xyz789",
      has_expected=True,
      limit=50
  )

  for sample in samples:
      print(f"{sample.id}: {sample.output.get('triage_level')}")
  ```

  ```bash cURL theme={null}
  curl "https://api.akhara.ai/v1/datasets/ds_xyz789/samples?has_expected=true&limit=50" \
    -H "Authorization: Bearer rb_live_xxxxxxxx"
  ```
</CodeGroup>

***

## Get Sample

Retrieve a specific sample by ID.

<EndpointBlock method="GET" path="/v1/datasets/{dataset_id}/samples/{sample_id}" />

### Example Request

<CodeGroup>
  ```python Python theme={null}
  sample = client.datasets.get_sample(
      dataset="ds_xyz789",
      sample="smp_abc123"
  )

  print(sample.input)
  print(sample.output)
  print(sample.expected)
  ```

  ```bash cURL theme={null}
  curl "https://api.akhara.ai/v1/datasets/ds_xyz789/samples/smp_abc123" \
    -H "Authorization: Bearer rb_live_xxxxxxxx"
  ```
</CodeGroup>

***

## Export Dataset

Export a dataset to various formats.

<EndpointBlock method="POST" path="/v1/datasets/{dataset_id}/export" />

### Request Body

| Parameter     | Type    | Required | Description                              |
| ------------- | ------- | -------- | ---------------------------------------- |
| `format`      | string  | Yes      | `json`, `jsonl`, `csv`, `parquet`        |
| `include_phi` | boolean | No       | Include PHI fields (requires permission) |
| `filters`     | object  | No       | Filter samples to export                 |

### Example Request

<CodeGroup>
  ```python Python theme={null}
  export = client.datasets.export(
      dataset="ds_xyz789",
      format="jsonl",
      include_phi=False
  )

  # Download when ready
  export.wait()
  export.download("q1_triage_calls.jsonl")
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.akhara.ai/v1/datasets/ds_xyz789/export" \
    -H "Authorization: Bearer rb_live_xxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{"format": "jsonl", "include_phi": false}'
  ```
</CodeGroup>

### Response

```json theme={null}
{
  "id": "exp_xyz123",
  "object": "export",
  "status": "processing",
  "format": "jsonl",
  "dataset": "ds_xyz789",
  "sample_count": 1247,
  "download_url": null,
  "expires_at": null,
  "created_at": "2024-01-15T11:00:00Z"
}
```

***

## Related

<CardGroup cols={2}>
  <Card title="Evaluation APIs" icon="flask" href="/evaluation/api-reference/evaluations">
    Run evaluations on your datasets
  </Card>

  <Card title="Sample Schemas" icon="code" href="/evaluation/api-reference/samples/schemas">
    Schema definitions for each modality
  </Card>
</CardGroup>