Klarety

API reference

Base URL, authentication, conventions and the public endpoint areas of the Klarety API.

For devs

The Klarety API is what the Python and the app use. Call it from any language that speaks HTTPS and JSON.

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.

Base URL

https://api.klarety.ai/v1

All requests use HTTPS with JSON bodies.

Authentication

Exchange your key for a token

POST/v1/token
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).

Send it on every request

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

Exchange the key again before the hour is up.

See Authentication for keys and rotation.

Conventions

Errors

Every failure is an RFC 9457 application/problem+json body with type, title, status, detail and instance. See Errors.

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

  • 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

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

Endpoint areas

Account and limits

GET/v1/account
GET/v1/whoami
GET/v1/limits
GET/v1/usage/storage

SQL and Spark

POST/v1/sql
GET/v1/sql/statements/{statement_id}
POST/v1/sql/estimate
GET/v1/sql/results/{result_id}
GET/v1/spark/status
POST/v1/spark/session
DELETE/v1/spark/session/{session_id}

Tables and schemas

GET/v1/schemas
GET/v1/tables
POST/v1/tables
GET/v1/tables/{name}
GET/v1/tables/{name}/rows
POST/v1/tables/{name}/rows/edit
PATCH/v1/tables/{name}/columns
GET/v1/tables/{name}/snapshots
POST/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

POST/v1/ingest/preview
POST/v1/ingest
GET/v1/ingest/{run_id}
POST/v1/uploads
POST/v1/uploads/complete

Jobs

POST/v1/batch-jobs
POST/v1/jobs
GET/v1/jobs/{job_id}
DELETE/v1/jobs/{job_id}

Files and folders

GET/v1/folders
GET/v1/folders/{folder_id}/entries
POST/v1/files/uploads
GET/v1/files
GET/v1/files/{file_id}/link
POST/v1/folders/{folder_id}/access/grants
POST/v1/folders/{folder_id}/watches

Connections

GET/v1/connections
POST/v1/connections
GET/v1/connections/{connection_id}/grant-policy
POST/v1/connections/{connection_id}/test
POST/v1/connections/{connection_id}/read
GET/v1/knowledge-graph
PUT/v1/knowledge-graph
GET/v1/knowledge-graph/overview
POST/v1/knowledge-graph/around
POST/v1/knowledge-graph/paths
POST/v1/search

Agents

GET/v1/projects/{project_id}/agents
POST/v1/projects/{project_id}/agents/{name}/drafts
POST/v1/projects/{project_id}/agents/{name}/runs
GET/v1/projects/{project_id}/agent-runs/{run_id}
POST/v1/projects/{project_id}/agent-runs/{run_id}/answers
POST/v1/projects/{project_id}/agent-runs/{run_id}/stop

Projects and deploys

GET/v1/projects
POST/v1/projects
GET/v1/projects/{project_id}
POST/v1/projects/{project_id}/deploys
GET/v1/projects/{project_id}/deploys/{deploy_id}
GET/v1/projects/{project_id}/logs/lines

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

Next steps

On this page

Base URLAuthenticationExchange your key for a tokenSend it on every requestConventionsErrorsPaginationSafe retriesSizesEndpoint areasAccount and limitsSQL and SparkTables and schemasIngest and uploadsJobsFiles and foldersConnectionsKnowledge graph and searchAgentsProjects and deploysNext steps