# API reference

The Klarety API is what the Python <Term id="sdk">SDK</Term> and the app use. Call it from any language that speaks HTTPS and JSON.

<Callout type="info" title="Full reference coming">
A generated reference with every field is coming. Until then, this page lists the endpoint areas and the SDK pages show each call in use.
</Callout>

## Base URL [#base-url]

```text
https://api.klarety.ai/v1
```

All requests use HTTPS with JSON bodies.

## Authentication [#authentication]

<Steps>
<Step>
### Exchange your key for a token [#exchange-your-key-for-a-token]

<Endpoint method="POST" path="/v1/token" />

```bash
curl -s https://api.klarety.ai/v1/token \
  -H "Content-Type: application/json" \
  -d "{\"api_key\": \"$KLARETY_API_KEY\"}"
```

The answer has `access_token`, `token_type` (`Bearer`) and `expires_in` (3600 seconds).
</Step>
<Step>
### Send it on every request [#send-it-on-every-request]

```bash
curl -s https://api.klarety.ai/v1/account -H "Authorization: Bearer $TOKEN"
```

Exchange the key again before the hour is up.
</Step>
</Steps>

See [Authentication](/docs/developers/authentication) for keys and rotation.

## Conventions [#conventions]

### Errors [#errors]

Every failure is an RFC 9457 `application/problem+json` body with `type`, `title`, `status`, `detail` and `instance`. See [Errors](/docs/developers/errors).

### Pagination [#pagination]

List endpoints return one page and a cursor. Pass it back for the next page; an empty or missing cursor means the last page. Its name depends on the endpoint (`next_cursor` or `next`, sent back as `cursor` or `after`). The SDK pages for you.

### Safe retries [#safe-retries]

- `POST /v1/sql` takes a `statement_id` (a UUID you choose). Resending it never runs the statement twice; it returns the answer, or `"state": "running"` to ask again at `GET /v1/sql/statements/{statement_id}`.
- `POST /v1/tables/{name}/rows/edit` takes a `write_id`. A write that already landed is answered as saved.

### Sizes [#sizes]

Request bodies are limited to 1 MiB. Files go through upload links that last one hour.

## Endpoint areas [#endpoint-areas]

### Account and limits [#account-and-limits]

<Endpoint method="GET" path="/v1/account" />
<Endpoint method="GET" path="/v1/whoami" />
<Endpoint method="GET" path="/v1/limits" />
<Endpoint method="GET" path="/v1/usage/storage" />

### SQL and Spark [#sql-and-spark]

<Endpoint method="POST" path="/v1/sql" />
<Endpoint method="GET" path="/v1/sql/statements/{statement_id}" />
<Endpoint method="POST" path="/v1/sql/estimate" />
<Endpoint method="GET" path="/v1/sql/results/{result_id}" />
<Endpoint method="GET" path="/v1/spark/status" />
<Endpoint method="POST" path="/v1/spark/session" />
<Endpoint method="DELETE" path="/v1/spark/session/{session_id}" />

### Tables and schemas [#tables-and-schemas]

<Endpoint method="GET" path="/v1/schemas" />
<Endpoint method="GET" path="/v1/tables" />
<Endpoint method="POST" path="/v1/tables" />
<Endpoint method="GET" path="/v1/tables/{name}" />
<Endpoint method="GET" path="/v1/tables/{name}/rows" />
<Endpoint method="POST" path="/v1/tables/{name}/rows/edit" />
<Endpoint method="PATCH" path="/v1/tables/{name}/columns" />
<Endpoint method="GET" path="/v1/tables/{name}/snapshots" />
<Endpoint method="POST" path="/v1/tables/{name}/rollback" />

Also: expectations, column docs, quality, changes, authors, erase, delete and restore under `/v1/tables/{name}/...`, and restores of earlier copies under `/v1/restores`.

### Ingest and uploads [#ingest-and-uploads]

<Endpoint method="POST" path="/v1/ingest/preview" />
<Endpoint method="POST" path="/v1/ingest" />
<Endpoint method="GET" path="/v1/ingest/{run_id}" />
<Endpoint method="POST" path="/v1/uploads" />
<Endpoint method="POST" path="/v1/uploads/complete" />

### Jobs [#jobs]

<Endpoint method="POST" path="/v1/batch-jobs" />
<Endpoint method="POST" path="/v1/jobs" />
<Endpoint method="GET" path="/v1/jobs/{job_id}" />
<Endpoint method="DELETE" path="/v1/jobs/{job_id}" />

### Files and folders [#files-and-folders]

<Endpoint method="GET" path="/v1/folders" />
<Endpoint method="GET" path="/v1/folders/{folder_id}/entries" />
<Endpoint method="POST" path="/v1/files/uploads" />
<Endpoint method="GET" path="/v1/files" />
<Endpoint method="GET" path="/v1/files/{file_id}/link" />
<Endpoint method="POST" path="/v1/folders/{folder_id}/access/grants" />
<Endpoint method="POST" path="/v1/folders/{folder_id}/watches" />

### Connections [#connections]

<Endpoint method="GET" path="/v1/connections" />
<Endpoint method="POST" path="/v1/connections" />
<Endpoint method="GET" path="/v1/connections/{connection_id}/grant-policy" />
<Endpoint method="POST" path="/v1/connections/{connection_id}/test" />
<Endpoint method="POST" path="/v1/connections/{connection_id}/read" />

### Knowledge graph and search [#knowledge-graph-and-search]

<Endpoint method="GET" path="/v1/knowledge-graph" />
<Endpoint method="PUT" path="/v1/knowledge-graph" />
<Endpoint method="GET" path="/v1/knowledge-graph/overview" />
<Endpoint method="POST" path="/v1/knowledge-graph/around" />
<Endpoint method="POST" path="/v1/knowledge-graph/paths" />
<Endpoint method="POST" path="/v1/search" />

### Agents [#agents]

<Endpoint method="GET" path="/v1/projects/{project_id}/agents" />
<Endpoint method="POST" path="/v1/projects/{project_id}/agents/{name}/drafts" />
<Endpoint method="POST" path="/v1/projects/{project_id}/agents/{name}/runs" />
<Endpoint method="GET" path="/v1/projects/{project_id}/agent-runs/{run_id}" />
<Endpoint method="POST" path="/v1/projects/{project_id}/agent-runs/{run_id}/answers" />
<Endpoint method="POST" path="/v1/projects/{project_id}/agent-runs/{run_id}/stop" />

### Projects and deploys [#projects-and-deploys]

<Endpoint method="GET" path="/v1/projects" />
<Endpoint method="POST" path="/v1/projects" />
<Endpoint method="GET" path="/v1/projects/{project_id}" />
<Endpoint method="POST" path="/v1/projects/{project_id}/deploys" />
<Endpoint method="GET" path="/v1/projects/{project_id}/deploys/{deploy_id}" />
<Endpoint method="GET" path="/v1/projects/{project_id}/logs/lines" />

Also: project secrets and variables, members, domains, shared ports and webhooks under `/v1/projects/{project_id}/...`.

## Next steps [#next-steps]

- [SDK quickstart](/docs/developers) to use the API from Python.
- [Errors](/docs/developers/errors) for status codes and retries.
- [Limits and rate limits](/docs/developers/limits) for what your plan allows.