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

# Public API

> API key-authenticated endpoints for programmatic access, CI/CD integrations, and external tools.

The public API uses API key authentication (not JWT). Create keys in **Settings > API Keys**.

## Health check

<Note>
  This endpoint requires no authentication.
</Note>

```bash theme={null}
curl https://orca-klavest.app/api/v1/public/health
```

```json theme={null}
{
  "data": {
    "status": "ok",
    "version": "1.0.0"
  }
}
```

## Upload a file

Upload a file for classification via multipart form data. Requires `scan` scope.

```bash theme={null}
curl -X POST -H "Authorization: Bearer orca_live_abc123..." \
  -F "file=@data.csv" \
  https://orca-klavest.app/api/v1/public/upload
```

```json theme={null}
{
  "data": {
    "job_id": "e5f6g7h8",
    "file_name": "data.csv",
    "status": "queued"
  }
}
```

## Get job status

Poll job status and retrieve results when complete. Requires `read` scope.

```bash theme={null}
curl -H "Authorization: Bearer orca_live_abc123..." \
  https://orca-klavest.app/api/v1/public/jobs/{job_id}
```

```json theme={null}
{
  "data": {
    "job_id": "e5f6g7h8",
    "status": "completed",
    "progress": 100,
    "file_id": 88,
    "columns": [
      {
        "name": "email",
        "classification": "PII / Email",
        "confidence": 0.97
      }
    ]
  }
}
```

## Trigger a scan

Trigger a classification scan on a connected data source. Requires `scan` scope.

```bash theme={null}
curl -X POST -H "Authorization: Bearer orca_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"source_id": 5, "table_name": "users"}' \
  https://orca-klavest.app/api/v1/public/scan/trigger
```

```json theme={null}
{
  "data": {
    "scan_id": "a1b2c3d4",
    "status": "queued",
    "estimated_tokens": 15
  }
}
```

## Get scan status

Poll scan status. Requires `scan` scope.

```bash theme={null}
curl -H "Authorization: Bearer orca_live_abc123..." \
  https://orca-klavest.app/api/v1/public/scan/{scan_id}/status
```

## List alerts

List alerts filtered by severity and date. Requires `read` scope.

```bash theme={null}
curl -H "Authorization: Bearer orca_live_abc123..." \
  "https://orca-klavest.app/api/v1/public/alerts?severity=critical&since=2024-01-01"
```

```json theme={null}
{
  "data": [
    {
      "id": 12,
      "severity": "critical",
      "message": "PII detected in production table",
      "created_at": "2024-11-14T12:00:00Z"
    }
  ],
  "meta": { "total": 1, "page": 1 }
}
```

## Get lineage graph

Retrieve the data lineage graph for your organisation. Requires `read` scope.

```bash theme={null}
curl -H "Authorization: Bearer orca_live_abc123..." \
  https://orca-klavest.app/api/v1/public/lineage
```

## Create lineage edge

Add a lineage relationship between nodes. Requires `write` scope.

```bash theme={null}
curl -X POST -H "Authorization: Bearer orca_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"source_node_id": "...", "target_node_id": "..."}' \
  https://orca-klavest.app/api/v1/public/lineage/edges
```

## Evaluate contract

Evaluate a data contract against the latest results. Requires `read` scope.

```bash theme={null}
curl -H "Authorization: Bearer orca_live_abc123..." \
  "https://orca-klavest.app/api/v1/public/contracts/evaluate?contract_id=3"
```