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

# Quickstart

# Quickstart

Get your first synthetic dataset validated in under 5 minutes. This guide walks you through uploading a dataset, running a full validation, and retrieving your scores.

<Info>
  You will need an API key to follow this guide. If you do not have one yet, sign up at [validate.lucitra.ai](https://validate.lucitra.ai) and generate a key from the dashboard.
</Info>

<Steps>
  ### Get your API key

  Log in to [validate.lucitra.ai](https://validate.lucitra.ai) and navigate to **Settings > API Keys**. Click **Create Key** and copy the value. API keys start with the `luci_` prefix.

  <Warning>
    Store your API key securely. It will only be displayed once. If you lose it, revoke the old key and generate a new one.
  </Warning>

  Set your key as an environment variable for the rest of this guide:

  <CodeGroup>
    ```bash bash theme={null}
    export LUCITRA_API_KEY="luci_your_api_key"
    ```

    ```python python theme={null}
    import os

    api_key = os.environ.get("LUCITRA_API_KEY", "luci_your_api_key")
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    }
    ```
  </CodeGroup>

  ### Upload a dataset

  Create a dataset record and get a signed upload URL. Supported formats are `coco`, `kitti`, `nuscenes`, and `custom`.

  <CodeGroup>
    ```bash curl theme={null}
    curl -X POST https://api.lucitra.io/v1/datasets \
      -H "Authorization: Bearer $LUCITRA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "project_id": "proj_abc123",
        "name": "warehouse-pick-v2",
        "format": "coco"
      }'
    ```

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

    response = requests.post(
        "https://api.lucitra.io/v1/datasets",
        headers=headers,
        json={
            "project_id": "proj_abc123",
            "name": "warehouse-pick-v2",
            "format": "coco",
        },
    )
    data = response.json()
    dataset_id = data["id"]
    upload_url = data["upload_url"]

    print(f"Dataset ID: {dataset_id}")
    print(f"Upload URL: {upload_url}")
    ```
  </CodeGroup>

  The response includes a `dataset_id` and a signed `upload_url`. Upload your dataset archive to the signed URL:

  <CodeGroup>
    ```bash curl theme={null}
    curl -X PUT "$UPLOAD_URL" \
      -H "Content-Type: application/zip" \
      --data-binary @warehouse-pick-v2.zip
    ```

    ```python python theme={null}
    with open("warehouse-pick-v2.zip", "rb") as f:
        upload_response = requests.put(
            upload_url,
            headers={"Content-Type": "application/zip"},
            data=f,
        )

    print(f"Upload status: {upload_response.status_code}")
    ```
  </CodeGroup>

  <Tip>
    Datasets can be `.zip` or `.tar.gz` archives. The archive should contain your annotation files and an optional `metadata.json` at the root.
  </Tip>

  ### Run validation

  Start a full validation across all four dimensions: coverage, physics plausibility, distribution quality, and sim-to-real gap.

  <CodeGroup>
    ```bash curl theme={null}
    curl -X POST https://api.lucitra.io/v1/validate/full \
      -H "Authorization: Bearer $LUCITRA_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "dataset_id": "ds_abc123"
      }'
    ```

    ```python python theme={null}
    validation = requests.post(
        "https://api.lucitra.io/v1/validate/full",
        headers=headers,
        json={
            "dataset_id": dataset_id,
        },
    )
    run = validation.json()
    run_id = run["run_id"]

    print(f"Validation started: {run_id}")
    ```
  </CodeGroup>

  The response returns a `run_id` that you will use to check progress and retrieve results.

  ### Poll for completion

  Validation runs asynchronously. Poll the status endpoint until `status` is `completed`.

  <CodeGroup>
    ```bash curl theme={null}
    curl https://api.lucitra.io/v1/validate/$RUN_ID/status \
      -H "Authorization: Bearer $LUCITRA_API_KEY"
    ```

    ```python python theme={null}
    import time

    while True:
        status_response = requests.get(
            f"https://api.lucitra.io/v1/validate/{run_id}/status",
            headers=headers,
        )
        status = status_response.json()

        print(f"Status: {status['status']}")

        if status["status"] == "completed":
            report_id = status["report_id"]
            break
        elif status["status"] == "failed":
            print(f"Error: {status['error']}")
            break

        time.sleep(2)
    ```
  </CodeGroup>

  <Note>
    Validation typically completes in 30 to 90 seconds depending on dataset size. The status endpoint returns `queued`, `running`, `completed`, or `failed`.
  </Note>

  ### Get your report

  Once validation completes, retrieve the full report with scores and detailed analysis.

  <CodeGroup>
    ```bash curl theme={null}
    curl https://api.lucitra.io/v1/reports/$REPORT_ID \
      -H "Authorization: Bearer $LUCITRA_API_KEY"
    ```

    ```python python theme={null}
    report = requests.get(
        f"https://api.lucitra.io/v1/reports/{report_id}",
        headers=headers,
    )
    result = report.json()

    print(f"Overall Score: {result['scores']['overall']}/100")
    print(f"Coverage: {result['scores']['coverage']}/100")
    print(f"Physics: {result['scores']['physics_plausibility']}/100")
    print(f"Distribution: {result['scores']['distribution_quality']}/100")
    print(f"Sim-to-Real: {result['scores']['sim_to_real_gap']}/100")
    ```
  </CodeGroup>

  The report includes:

  * **Scores** — 0 to 100 for each dimension and an overall composite score
  * **Findings** — specific issues detected, ranked by severity
  * **Recommendations** — actionable steps to improve data quality
</Steps>

## Next Steps

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/authentication">
    Understand API keys, rate limits, and enterprise tiers.
  </Card>

  <Card title="Validation Guide" icon="magnifying-glass" href="/guides/validation">
    Configure thresholds, custom rules, and dimension weights.
  </Card>

  <Card title="CLI" icon="terminal" href="/cli/installation">
    Run validations from your terminal or CI/CD pipeline.
  </Card>
</CardGroup>