# API Reference

Source: https://www.hotdata.dev/docs/api-reference
Site index: https://www.hotdata.dev/llms.txt

Hotdata exposes a `/v1/*` HTTP API at [api.hotdata.dev](https://api.hotdata.dev).

[OpenAPI 3.1 specification](/openapi.yaml)

## Authentication

Most `/v1/*` endpoints require these headers:

```http
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](/docs/api-reference/workspaces#list-workspaces) |
| `POST` | `/v1/workspaces` | [Create a workspace](/docs/api-reference/workspaces#create-a-workspace) |
| `DELETE` | `/v1/workspaces/{public_id}` | [Delete a workspace](/docs/api-reference/workspaces#delete-a-workspace) |

### Query

| Method | Path | Operation |
| ------ | ---- | --------- |
| `POST` | `/v1/query` | [Execute SQL query](/docs/api-reference/query#execute-sql-query) |

### Information Schema

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/information_schema` | [List tables](/docs/api-reference/information-schema#list-tables) |

### Results

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/results` | [List results](/docs/api-reference/results#list-results) |
| `GET` | `/v1/results/{id}` | [Get result](/docs/api-reference/results#get-result) |

### Query Runs

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/query-runs` | [List query runs](/docs/api-reference/query-runs#list-query-runs) |
| `GET` | `/v1/query-runs/{id}` | [Get query run](/docs/api-reference/query-runs#get-query-run) |

### Uploads

| Method | Path | Operation |
| ------ | ---- | --------- |
| `POST` | `/v1/uploads` | [Create upload session](/docs/api-reference/uploads#create-upload-session) |
| `POST` | `/v1/uploads/batch` | [Create upload sessions in bulk](/docs/api-reference/uploads#create-upload-sessions-in-bulk) |
| `POST` | `/v1/uploads/{upload_id}/finalize` | [Finalize upload](/docs/api-reference/uploads#finalize-upload) |
| `POST` | `/v1/uploads/{upload_id}/parts` | [Mint upload part URLs](/docs/api-reference/uploads#mint-upload-part-urls) |

### Saved Queries

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/queries` | [List saved queries](/docs/api-reference/saved-queries#list-saved-queries) |
| `POST` | `/v1/queries` | [Create saved query](/docs/api-reference/saved-queries#create-saved-query) |
| `GET` | `/v1/queries/{id}` | [Get saved query](/docs/api-reference/saved-queries#get-saved-query) |
| `PUT` | `/v1/queries/{id}` | [Update saved query](/docs/api-reference/saved-queries#update-saved-query) |
| `DELETE` | `/v1/queries/{id}` | [Delete saved query](/docs/api-reference/saved-queries#delete-saved-query) |
| `POST` | `/v1/queries/{id}/execute` | [Execute saved query](/docs/api-reference/saved-queries#execute-saved-query) |
| `GET` | `/v1/queries/{id}/versions` | [List saved query versions](/docs/api-reference/saved-queries#list-saved-query-versions) |

### Indexes

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/indexes` | [List indexes across tables in a database](/docs/api-reference/indexes#list-indexes-across-tables-in-a-database) |

### Embedding Providers

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/embedding-providers` | [List embedding providers](/docs/api-reference/embedding-providers#list-embedding-providers) |
| `POST` | `/v1/embedding-providers` | [Create embedding provider](/docs/api-reference/embedding-providers#create-embedding-provider) |
| `GET` | `/v1/embedding-providers/{id}` | [Get embedding provider](/docs/api-reference/embedding-providers#get-embedding-provider) |
| `PUT` | `/v1/embedding-providers/{id}` | [Update embedding provider](/docs/api-reference/embedding-providers#update-embedding-provider) |
| `DELETE` | `/v1/embedding-providers/{id}` | [Delete embedding provider](/docs/api-reference/embedding-providers#delete-embedding-provider) |

### Jobs

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/jobs` | [List jobs](/docs/api-reference/jobs#list-jobs) |
| `GET` | `/v1/jobs/{id}` | [Get job status](/docs/api-reference/jobs#get-job-status) |

### Database context

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/databases/{database_id}/context` | [List database contexts](/docs/api-reference/database-context#list-database-contexts) |
| `POST` | `/v1/databases/{database_id}/context` | [Create or update database context](/docs/api-reference/database-context#create-or-update-database-context) |
| `GET` | `/v1/databases/{database_id}/context/{name}` | [Get one database context](/docs/api-reference/database-context#get-one-database-context) |
| `DELETE` | `/v1/databases/{database_id}/context/{name}` | [Delete database context](/docs/api-reference/database-context#delete-database-context) |

### Databases

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/databases` | [List databases](/docs/api-reference/databases#list-databases) |
| `POST` | `/v1/databases` | [Create database](/docs/api-reference/databases#create-database) |
| `POST` | `/v1/databases/bulk` | [Create many databases at once](/docs/api-reference/databases#create-many-databases-at-once) |
| `GET` | `/v1/databases/bulk/{batch_id}` | [Get a database batch](/docs/api-reference/databases#get-a-database-batch) |
| `DELETE` | `/v1/databases/bulk/{batch_id}` | [Delete a database batch](/docs/api-reference/databases#delete-a-database-batch) |
| `GET` | `/v1/databases/by-name` | [Look up a database by name](/docs/api-reference/databases#look-up-a-database-by-name) |
| `GET` | `/v1/databases/count` | [Count databases](/docs/api-reference/databases#count-databases) |
| `GET` | `/v1/databases/{database_id}` | [Get database](/docs/api-reference/databases#get-database) |
| `DELETE` | `/v1/databases/{database_id}` | [Delete database](/docs/api-reference/databases#delete-database) |
| `POST` | `/v1/databases/{database_id}/catalogs` | [Attach catalog to database](/docs/api-reference/databases#attach-catalog-to-database) |
| `DELETE` | `/v1/databases/{database_id}/catalogs/{connection_id}` | [Detach catalog from database](/docs/api-reference/databases#detach-catalog-from-database) |
| `POST` | `/v1/databases/{database_id}/fork` | [Fork database](/docs/api-reference/databases#fork-database) |
| `GET` | `/v1/databases/{database_id}/lineage` | [Get database lineage](/docs/api-reference/databases#get-database-lineage) |
| `POST` | `/v1/databases/{database_id}/schemas` | [Add schema to database default catalog](/docs/api-reference/databases#add-schema-to-database-default-catalog) |
| `POST` | `/v1/databases/{database_id}/schemas/{schema}/tables` | [Add table to database default catalog](/docs/api-reference/databases#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](/docs/api-reference/databases#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](/docs/api-reference/databases#load-database-table-from-inline-data-upload-or-query-result) |

### Usage

| Method | Path | Operation |
| ------ | ---- | --------- |
| `GET` | `/v1/usage` | [Get workspace usage snapshot](/docs/api-reference/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**

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

### Error

Used by 11 responses.

- `error` `string` — **required**. Machine-readable error code.

```json
{
  "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.