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

# Compliance

# Compliance

The compliance engine provides audit trails, data provenance tracking, model cards, regulatory reports, and certification tokens for teams operating in regulated environments.

<Warning>
  All compliance features require an **Enterprise** tier subscription. API calls on lower tiers return **403 Forbidden**.
</Warning>

## Audit Trail

Every significant action in your Lucitra project is automatically recorded as an immutable audit event. No setup is required -- events are captured as soon as you use the platform.

### Recorded Events

| Event Type                     | Triggered When                               |
| ------------------------------ | -------------------------------------------- |
| `dataset.created`              | A new dataset is created                     |
| `validation.started`           | A validation run begins                      |
| `report.pdf_exported`          | A report is exported as PDF                  |
| `compliance_report.created`    | A compliance report is generated             |
| `provenance.created`           | A provenance record is attached to a dataset |
| `model_card.created`           | A model card is created                      |
| `certification_token.created`  | A certification token is issued              |
| `certification_token.revoked`  | A certification token is revoked             |
| `drift_check.started`          | A drift detection check begins               |
| `revalidation_trigger.created` | A revalidation trigger is configured         |

### Query Audit Events

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lucitra.io/v1/audit/events?event_type=validation.started&resource_type=dataset&since=2026-01-01&until=2026-03-06&limit=50" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

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

  resp = requests.get(
      "https://api.lucitra.io/v1/audit/events",
      headers={"Authorization": "Bearer luci_your_api_key"},
      params={
          "event_type": "validation.started",
          "resource_type": "dataset",
          "since": "2026-01-01",
          "until": "2026-03-06",
          "limit": 50,
      },
  )
  events = resp.json()
  ```
</CodeGroup>

<ParamField query="event_type" type="string">
  Filter by event type (e.g., `validation.started`). Omit to return all types.
</ParamField>

<ParamField query="resource_type" type="string">
  Filter by resource type (e.g., `dataset`, `report`, `model_card`).
</ParamField>

<ParamField query="since" type="string">
  Start date in `YYYY-MM-DD` format.
</ParamField>

<ParamField query="until" type="string">
  End date in `YYYY-MM-DD` format.
</ParamField>

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

***

## Provenance

Provenance records link each dataset to the exact simulation parameters, random seeds, source code, and environment used to generate it. This creates a complete reproducibility chain from raw data back to its origin.

### Record Provenance

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.lucitra.io/v1/provenance \
    -H "Authorization: Bearer luci_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "dataset_id": "ds_7kx9m2",
      "simulator": "isaac-sim",
      "simulator_version": "4.5.0",
      "generation_params": {
        "domain_randomization": true,
        "lighting_variation": "high",
        "object_density": 0.7
      },
      "random_seeds": [42, 1337, 9001],
      "content_hash": "sha256:a1b2c3d4e5f6...",
      "source_repo": "https://github.com/acme/sim-scenes",
      "source_commit": "abc123def456",
      "host_info": {
        "gpu": "A100-80GB",
        "driver": "535.129.03",
        "os": "Ubuntu 22.04"
      }
    }'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.lucitra.io/v1/provenance",
      headers={"Authorization": "Bearer luci_your_api_key"},
      json={
          "dataset_id": "ds_7kx9m2",
          "simulator": "isaac-sim",
          "simulator_version": "4.5.0",
          "generation_params": {
              "domain_randomization": True,
              "lighting_variation": "high",
              "object_density": 0.7,
          },
          "random_seeds": [42, 1337, 9001],
          "content_hash": "sha256:a1b2c3d4e5f6...",
          "source_repo": "https://github.com/acme/sim-scenes",
          "source_commit": "abc123def456",
          "host_info": {
              "gpu": "A100-80GB",
              "driver": "535.129.03",
              "os": "Ubuntu 22.04",
          },
      },
  )
  ```
</CodeGroup>

<ParamField body="dataset_id" type="string" required>
  The dataset to attach provenance to.
</ParamField>

<ParamField body="simulator" type="string" required>
  Name of the simulator used (e.g., `isaac-sim`, `carla`, `unity`).
</ParamField>

<ParamField body="simulator_version" type="string" required>
  Version string of the simulator.
</ParamField>

<ParamField body="generation_params" type="object" required>
  The simulation parameters used to generate this dataset. Structure is freeform.
</ParamField>

<ParamField body="random_seeds" type="array" required>
  Random seeds used during generation, enabling exact reproducibility.
</ParamField>

<ParamField body="content_hash" type="string" required>
  Cryptographic hash of the dataset contents for integrity verification.
</ParamField>

<ParamField body="source_repo" type="string">
  URL of the source repository containing scene definitions.
</ParamField>

<ParamField body="source_commit" type="string">
  Git commit SHA of the source code used during generation.
</ParamField>

<ParamField body="host_info" type="object">
  Hardware and software environment details of the generation host.
</ParamField>

### Get Provenance Chain

Retrieve the full ordered provenance chain for a dataset. If the dataset was derived from other datasets, the chain includes all ancestors.

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

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

***

## Model Cards

Model cards document the relationship between training data, validation results, and the models trained on that data. They provide a structured record for internal review and regulatory submissions.

### Create a Model Card

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.lucitra.io/v1/model-cards \
    -H "Authorization: Bearer luci_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "project_id": "proj_abc123",
      "name": "warehouse-perception-v3",
      "report_ids": ["rpt_8abc1234", "rpt_9def5678"],
      "training_metadata": {
        "model_architecture": "yolov8-l",
        "framework": "ultralytics",
        "epochs": 300,
        "final_map50": 0.89
      }
    }'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.lucitra.io/v1/model-cards",
      headers={"Authorization": "Bearer luci_your_api_key"},
      json={
          "project_id": "proj_abc123",
          "name": "warehouse-perception-v3",
          "report_ids": ["rpt_8abc1234", "rpt_9def5678"],
          "training_metadata": {
              "model_architecture": "yolov8-l",
              "framework": "ultralytics",
              "epochs": 300,
              "final_map50": 0.89,
          },
      },
  )
  model_card = resp.json()
  ```
</CodeGroup>

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

<ParamField body="name" type="string" required>
  A descriptive name for this model card.
</ParamField>

<ParamField body="report_ids" type="array" required>
  Validation report IDs to include. Links the model card to specific data quality assessments.
</ParamField>

<ParamField body="training_metadata" type="object" required>
  Training configuration and results. Structure is freeform but should include architecture, framework, and performance metrics.
</ParamField>

### Retrieve and List Model Cards

<CodeGroup>
  ```bash Get theme={null}
  curl "https://api.lucitra.io/v1/model-cards/mc_xyz789" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```bash List by project theme={null}
  curl "https://api.lucitra.io/v1/projects/proj_abc123/model-cards" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```bash Export PDF theme={null}
  curl "https://api.lucitra.io/v1/model-cards/mc_xyz789/pdf" \
    -H "Authorization: Bearer luci_your_api_key" \
    -o model-card.pdf
  ```
</CodeGroup>

***

## Compliance Reports

Generate regulatory compliance reports that map your validation results against specific standards. Reports are generated asynchronously and returned as downloadable documents.

### Supported Standards

<CardGroup cols={3}>
  <Card title="EU AI Act" icon="flag">
    European Union Artificial Intelligence Act. Required for high-risk AI systems deployed in the EU.
  </Card>

  <Card title="FDA 21 CFR Part 11" icon="file-medical">
    FDA regulations for electronic records and signatures. Required for medical device AI.
  </Card>

  <Card title="ISO 26262" icon="car">
    Functional safety standard for road vehicles. Required for automotive ADAS and AV systems.
  </Card>
</CardGroup>

### Generate a Compliance Report

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.lucitra.io/v1/compliance/report \
    -H "Authorization: Bearer luci_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "projectId": "proj_abc123",
      "reportIds": ["rpt_8abc1234", "rpt_9def5678"],
      "format": "pdf",
      "standard": "eu_ai_act"
    }'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.lucitra.io/v1/compliance/report",
      headers={"Authorization": "Bearer luci_your_api_key"},
      json={
          "projectId": "proj_abc123",
          "reportIds": ["rpt_8abc1234", "rpt_9def5678"],
          "format": "pdf",
          "standard": "eu_ai_act",
      },
  )
  # Returns 202 Accepted
  compliance = resp.json()
  ```
</CodeGroup>

<ParamField body="projectId" type="string" required>
  The project to generate the compliance report for.
</ParamField>

<ParamField body="reportIds" type="array" required>
  Validation report IDs to include in the compliance assessment.
</ParamField>

<ParamField body="format" type="string" required>
  Output format. Currently `pdf` is supported.
</ParamField>

<ParamField body="standard" type="string" required>
  Regulatory standard to assess against. One of `eu_ai_act`, `fda_21cfr11`, or `iso_26262`.
</ParamField>

<Info>
  Compliance report generation returns **202 Accepted**. Poll the report status or use a webhook to be notified when it is ready.
</Info>

### List, Get, and Download

<CodeGroup>
  ```bash List theme={null}
  curl "https://api.lucitra.io/v1/compliance/reports?project_id=proj_abc123" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```bash Get theme={null}
  curl "https://api.lucitra.io/v1/compliance/reports/cr_abc123" \
    -H "Authorization: Bearer luci_your_api_key"
  ```

  ```bash Download theme={null}
  curl -L "https://api.lucitra.io/v1/compliance/reports/cr_abc123/download" \
    -H "Authorization: Bearer luci_your_api_key" \
    -o compliance-report.pdf
  ```
</CodeGroup>

<Note>
  The download endpoint returns a **307 redirect** to a time-limited signed GCS URL. Use `-L` in cURL or `allow_redirects=True` in Python to follow the redirect automatically.
</Note>

***

## Certification Tokens

Certification tokens provide time-limited, read-only access to a compliance report without requiring API authentication. Use them to share audit-ready reports with external auditors, regulators, or certification bodies.

### Create a Certification Token

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.lucitra.io/v1/certification/tokens \
    -H "Authorization: Bearer luci_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "compliance_report_id": "cr_abc123",
      "name": "TUV-audit-march-2026",
      "expires_in_hours": 168,
      "max_access_count": 10,
      "auditor_name": "Dr. Maria Schmidt",
      "auditor_email": "m.schmidt@tuv.com"
    }'
  ```

  ```python Python theme={null}
  resp = requests.post(
      "https://api.lucitra.io/v1/certification/tokens",
      headers={"Authorization": "Bearer luci_your_api_key"},
      json={
          "compliance_report_id": "cr_abc123",
          "name": "TUV-audit-march-2026",
          "expires_in_hours": 168,
          "max_access_count": 10,
          "auditor_name": "Dr. Maria Schmidt",
          "auditor_email": "m.schmidt@tuv.com",
      },
  )
  token_data = resp.json()
  # Save token_data["token"] — it is only shown once
  ```
</CodeGroup>

<ParamField body="compliance_report_id" type="string" required>
  The compliance report to grant access to.
</ParamField>

<ParamField body="name" type="string" required>
  A descriptive name for tracking this token (e.g., the audit or auditor name).
</ParamField>

<ParamField body="expires_in_hours" type="integer" required>
  Token validity period in hours. Must be between 1 and 720 (30 days).
</ParamField>

<ParamField body="max_access_count" type="integer">
  Maximum number of times the token can be used. Null for unlimited access within the expiry window.
</ParamField>

<ParamField body="auditor_name" type="string">
  Name of the auditor or recipient for audit trail purposes.
</ParamField>

<ParamField body="auditor_email" type="string">
  Email of the auditor or recipient for audit trail purposes.
</ParamField>

<Accordion title="Response">
  ```json theme={null}
  {
    "id": "ctk_m2n3o4p5",
    "token": "cert_a1b2c3d4e5f6g7h8i9j0",
    "prefix": "cert_a1b2",
    "expires_at": "2026-03-13T12:00:00Z"
  }
  ```

  <ResponseField name="id" type="string" required>
    Token identifier for management operations.
  </ResponseField>

  <ResponseField name="token" type="string" required>
    The full certification token. Starts with `cert_`. Shown only once at creation time.
  </ResponseField>

  <ResponseField name="prefix" type="string" required>
    A short prefix for identifying the token without exposing the full value.
  </ResponseField>

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

<Warning>
  The `token` value is only returned at creation time. Store it securely and share it with the auditor through a secure channel. There is no way to retrieve the full token after this response.
</Warning>

### Public Report Access

Auditors access the compliance report using the token directly in the URL. No API key or authentication is required.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.lucitra.io/v1/certification/reports/cert_a1b2c3d4e5f6g7h8i9j0"
  ```

  ```text Browser theme={null}
  https://api.lucitra.io/v1/certification/reports/cert_a1b2c3d4e5f6g7h8i9j0
  ```
</CodeGroup>

<Tip>
  Share the full URL with auditors. They can open it directly in a browser to view the compliance report without needing a Lucitra account or API key.
</Tip>