API Reference

Hotdata exposes a /v1/* HTTP API at api.hotdata.dev.

OpenAPI 3.1 specification

/openapi.yamlView

Authentication

Most /v1/* endpoints require these headers:

Authorization: Bearer <api_token>
X-Workspace-Id: <workspace_id>

Authorization — Org-scoped API token obtained via CLI login or the dashboard.
X-Workspace-Id — Public ID of the target workspace.

Operations that need a narrower scope take an extra header — those are listed on the endpoint itself.

All endpoints

Workspaces

Method	Path	Operation
`GET`	`/v1/workspaces`	List workspaces
`POST`	`/v1/workspaces`	Create a workspace
`DELETE`	`/v1/workspaces/{public_id}`	Delete a workspace

Query

Method	Path	Operation
`POST`	`/v1/query`	Execute SQL query

Information Schema

Method	Path	Operation
`GET`	`/v1/information_schema`	List tables

Results

Method	Path	Operation
`GET`	`/v1/results`	List results
`GET`	`/v1/results/{id}`	Get result

Query Runs

Method	Path	Operation
`GET`	`/v1/query-runs`	List query runs
`GET`	`/v1/query-runs/{id}`	Get query run

Uploads

Method	Path	Operation
`POST`	`/v1/uploads`	Create upload session
`POST`	`/v1/uploads/batch`	Create upload sessions in bulk
`POST`	`/v1/uploads/{upload_id}/finalize`	Finalize upload
`POST`	`/v1/uploads/{upload_id}/parts`	Mint upload part URLs

Saved Queries

Method	Path	Operation
`GET`	`/v1/queries`	List saved queries
`POST`	`/v1/queries`	Create saved query
`GET`	`/v1/queries/{id}`	Get saved query
`PUT`	`/v1/queries/{id}`	Update saved query
`DELETE`	`/v1/queries/{id}`	Delete saved query
`POST`	`/v1/queries/{id}/execute`	Execute saved query
`GET`	`/v1/queries/{id}/versions`	List saved query versions

Indexes

Method	Path	Operation
`GET`	`/v1/indexes`	List indexes across tables in a database

Embedding Providers

Method	Path	Operation
`GET`	`/v1/embedding-providers`	List embedding providers
`POST`	`/v1/embedding-providers`	Create embedding provider
`GET`	`/v1/embedding-providers/{id}`	Get embedding provider
`PUT`	`/v1/embedding-providers/{id}`	Update embedding provider
`DELETE`	`/v1/embedding-providers/{id}`	Delete embedding provider

Jobs

Method	Path	Operation
`GET`	`/v1/jobs`	List jobs
`GET`	`/v1/jobs/{id}`	Get job status

Database context

Method	Path	Operation
`GET`	`/v1/databases/{database_id}/context`	List database contexts
`POST`	`/v1/databases/{database_id}/context`	Create or update database context
`GET`	`/v1/databases/{database_id}/context/{name}`	Get one database context
`DELETE`	`/v1/databases/{database_id}/context/{name}`	Delete database context

Databases

Method	Path	Operation
`GET`	`/v1/databases`	List databases
`POST`	`/v1/databases`	Create database
`POST`	`/v1/databases/bulk`	Create many databases at once
`GET`	`/v1/databases/bulk/{batch_id}`	Get a database batch
`DELETE`	`/v1/databases/bulk/{batch_id}`	Delete a database batch
`GET`	`/v1/databases/by-name`	Look up a database by name
`GET`	`/v1/databases/count`	Count databases
`GET`	`/v1/databases/{database_id}`	Get database
`DELETE`	`/v1/databases/{database_id}`	Delete database
`POST`	`/v1/databases/{database_id}/catalogs`	Attach catalog to database
`DELETE`	`/v1/databases/{database_id}/catalogs/{connection_id}`	Detach catalog from database
`POST`	`/v1/databases/{database_id}/fork`	Fork database
`GET`	`/v1/databases/{database_id}/lineage`	Get database lineage
`POST`	`/v1/databases/{database_id}/schemas`	Add schema to database default catalog
`POST`	`/v1/databases/{database_id}/schemas/{schema}/tables`	Add table to database default catalog
`PUT`	`/v1/databases/{database_id}/schemas/{schema}/tables/{table}/constant-per-key`	Declare which columns are constant per key
`POST`	`/v1/databases/{database_id}/schemas/{schema}/tables/{table}/loads`	Load database table from inline data, upload, or query result

Usage

Method	Path	Operation
`GET`	`/v1/usage`	Get workspace usage snapshot

Error responses

Failures carry a non-2xx HTTP status and a JSON body. Each endpoint lists the statuses it can return; the bodies use these shapes:

ApiErrorResponse

Standard error response body. Used by 84 responses.

error ApiErrorDetail — required. Error detail within an API error response
- code string — required
- message string — required

{
  "error": {
    "code": "string",
    "message": "string"
  }
}

Error

Used by 11 responses.

error string — required. Machine-readable error code.

{
  "error": "missing_authorization"
}

Rate limiting

API requests are rate limited. When a limit is exceeded the API returns 429 Too Many Requests with a Retry-After header giving the seconds to wait before retrying.