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

# Datasets

# Datasets

Upload, manage, and query synthetic training datasets. Lucitra accepts data in COCO, KITTI, nuScenes, or custom formats and stores it on Google Cloud Storage with signed upload URLs.

## Supported Formats

<CardGroup cols={4}>
  <Card title="COCO" icon="brackets-curly">
    Object detection, instance segmentation, and keypoints. The most common format for 2D vision tasks.
  </Card>

  <Card title="KITTI" icon="cube">
    3D bounding boxes, point clouds, and stereo pairs. Standard for autonomous driving benchmarks.
  </Card>

  <Card title="nuScenes" icon="layer-group">
    Multi-sensor, multi-frame sequences with ego pose. Designed for full autonomous driving stacks.
  </Card>

  <Card title="Custom" icon="code">
    Bring your own annotation schema. Define a format adapter and Lucitra handles the rest.
  </Card>
</CardGroup>

## Create a Dataset

Creating a dataset returns a time-limited signed URL for uploading your data file directly to cloud storage.

<Steps>
  <Step title="Create the dataset record">
    Send a `POST` request with your project ID, dataset name, format, and optional metadata.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.lucitra.io/v1/datasets \
        -H "Authorization: Bearer luci_your_api_key" \
        -H "Content-Type: application/json" \
        -d '{
          "project_id": "proj_abc123",
          "name": "warehouse-v3",
          "format": "coco",
          "metadata": {
            "simulator": "isaac-sim",
            "version": "4.5.0",
            "scene_count": 5000
          }
        }'
      ```

      ```python Python theme={null}
      import requests

      resp = requests.post(
          "https://api.lucitra.io/v1/datasets",
          headers={"Authorization": "Bearer luci_your_api_key"},
          json={
              "project_id": "proj_abc123",
              "name": "warehouse-v3",
              "format": "coco",
              "metadata": {
                  "simulator": "isaac-sim",
                  "version": "4.5.0",
                  "scene_count": 5000,
              },
          },
      )
      data = resp.json()
      ```
    </CodeGroup>

    <Accordion title="Response">
      ```json theme={null}
      {
        "id": "ds_7kx9m2",
        "upload_url": "https://storage.googleapis.com/lucitra-datasets/...",
        "expires_at": "2026-03-06T13:00:00Z"
      }
      ```

      <ResponseField name="id" type="string" required>
        Unique dataset identifier. Use this in validation and report endpoints.
      </ResponseField>

      <ResponseField name="upload_url" type="string" required>
        Pre-signed GCS URL for uploading your data file. Valid for 1 hour.
      </ResponseField>

      <ResponseField name="expires_at" type="string" required>
        ISO 8601 timestamp when the upload URL expires.
      </ResponseField>
    </Accordion>
  </Step>

  <Step title="Upload your data file">
    Use the signed URL from the response to upload your dataset archive via a `PUT` request.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X PUT "${UPLOAD_URL}" \
        -H "Content-Type: application/octet-stream" \
        --data-binary @warehouse-v3.tar.gz
      ```

      ```python Python theme={null}
      with open("warehouse-v3.tar.gz", "rb") as f:
          requests.put(
              data["upload_url"],
              headers={"Content-Type": "application/octet-stream"},
              data=f,
          )
      ```
    </CodeGroup>

    <Warning>
      The upload URL expires after **1 hour**. If it expires before your upload completes, create a new dataset to get a fresh URL.
    </Warning>
  </Step>
</Steps>

### Request Body

<ParamField body="project_id" type="string" required>
  The project this dataset belongs to.
</ParamField>

<ParamField body="name" type="string" required>
  A human-readable name for the dataset.
</ParamField>

<ParamField body="format" type="string" required>
  Annotation format. One of `coco`, `kitti`, `nuscenes`, or `custom`.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs for tracking simulator version, scene parameters, or any other context.
</ParamField>

## List Datasets

Retrieve all datasets belonging to a project with pagination support.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lucitra.io/v1/datasets?project_id=proj_abc123&limit=20&offset=0" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```python Python theme={null}
  resp = requests.get(
      "https://api.lucitra.io/v1/datasets",
      headers={"Authorization": "Bearer luci_your_api_key"},
      params={"project_id": "proj_abc123", "limit": 20, "offset": 0},
  )
  datasets = resp.json()
  ```
</CodeGroup>

<ParamField query="project_id" type="string" required>
  Filter datasets to this project.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Maximum number of datasets to return.
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of datasets to skip for pagination.
</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "datasets": [
      {
        "id": "ds_7kx9m2",
        "project_id": "proj_abc123",
        "name": "warehouse-v3",
        "format": "coco",
        "scene_count": 5000,
        "total_size_bytes": 2147483648,
        "uploaded_at": "2026-03-06T12:05:00Z"
      }
    ],
    "total": 1
  }
  ```

  <ResponseField name="datasets" type="array" required>
    Array of dataset objects.
  </ResponseField>

  <ResponseField name="total" type="integer" required>
    Total number of datasets matching the query, regardless of `limit` and `offset`.
  </ResponseField>
</Accordion>

## Get a Single Dataset

Retrieve full details for a specific dataset by ID.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lucitra.io/v1/datasets/ds_7kx9m2" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```python Python theme={null}
  resp = requests.get(
      "https://api.lucitra.io/v1/datasets/ds_7kx9m2",
      headers={"Authorization": "Bearer luci_your_api_key"},
  )
  dataset = resp.json()
  ```
</CodeGroup>

<Accordion title="Response">
  ```json theme={null}
  {
    "id": "ds_7kx9m2",
    "project_id": "proj_abc123",
    "name": "warehouse-v3",
    "gcs_path": "gs://lucitra-datasets/proj_abc123/ds_7kx9m2/warehouse-v3.tar.gz",
    "format": "coco",
    "scene_count": 5000,
    "total_size_bytes": 2147483648,
    "metadata": {
      "simulator": "isaac-sim",
      "version": "4.5.0",
      "scene_count": 5000
    },
    "uploaded_at": "2026-03-06T12:05:00Z"
  }
  ```

  <ResponseField name="id" type="string" required>
    Unique dataset identifier.
  </ResponseField>

  <ResponseField name="project_id" type="string" required>
    The project this dataset belongs to.
  </ResponseField>

  <ResponseField name="name" type="string" required>
    Human-readable dataset name.
  </ResponseField>

  <ResponseField name="gcs_path" type="string" required>
    Internal Google Cloud Storage path where the data is stored.
  </ResponseField>

  <ResponseField name="format" type="string" required>
    Annotation format: `coco`, `kitti`, `nuscenes`, or `custom`.
  </ResponseField>

  <ResponseField name="scene_count" type="integer" required>
    Number of scenes detected in the dataset after upload processing.
  </ResponseField>

  <ResponseField name="total_size_bytes" type="integer" required>
    Total size of the uploaded file in bytes.
  </ResponseField>

  <ResponseField name="metadata" type="object">
    User-provided metadata from dataset creation.
  </ResponseField>

  <ResponseField name="uploaded_at" type="string" required>
    ISO 8601 timestamp of when the upload completed.
  </ResponseField>
</Accordion>

<Tip>
  Use the `gcs_path` value when configuring provenance tracking in the compliance engine. It uniquely identifies the stored artifact.
</Tip>