Core Concepts

The foundations of every Hotdata integration: the object model includes workspaces, databases, catalogs, tables and authentication. Continue to Push Data (your systems send the data) or Pull Data (Hotdata fetches it). Field-by-field detail is in the API reference.

The object model

Four objects account for nearly every resource in the API, and they nest. Two request headers determine which of them a given request addresses.

Workspacework…: An isolated execution environment: nothing is shared across workspaces — not compute, not cache, not credentials. Each request names one in the X-Workspace-Id header. Most integrations use a single workspace; a per-customer integration typically provisions one per customer.
Databasedbid…: A query scope inside a workspace, created and deleted in a single call. It is the unit of work: create one for a job, load data into it, query it, and remove it. Setting expires_at makes that removal automatic. Named on a request in the X-Database-Id header.
Catalog: A named group of schemas and tables inside a database. Every database is created with one called default, which is where pushed data lands. Further catalogs can be attached alongside it, allowing a single query to span separate bodies of data.
Table: Holds the rows. Addressed in SQL as catalog.schema.table — default.main.orders for a table that has just been pushed. Identifiers are lowercased on receipt, and an undeclared table is created on its first load.

Two headers and a qualified name constitute the entire addressing scheme. X-Workspace-Id selects the engine, X-Database-Id selects the query scope within it, and the three-part name in the SQL resolves the rest. Pushed data lands in default.main unless directed elsewhere.

Global catalogs

The default catalog is local to its database. It is created with the database, removed with it, and cannot be attached anywhere else. Every other catalog is shareable: attaching one through POST /v1/databases/{database_id}/catalogs makes it visible inside that database, and the same catalog can be attached to as many databases as you need, at the same time.

A reference dataset is loaded once and attached wherever it is needed; each database joins it against its own local tables. Supply an alias to address it under a different name (an alias may not shadow default or the reserved catalog names). Detaching withdraws visibility rather than deleting data, and deleting a database removes its attachments while leaving the shared catalog intact.

Authentication

All calls are made to https://api.hotdata.dev under /v1. There is no per-workspace hostname and no token exchange to implement: an API token is issued once from the dashboard and sent unmodified on every request.

# the two headers on every request
Authorization: Bearer <api_token>
X-Workspace-Id: workm4lz2mp899l2i7h9lk9u84azg3

# create a database, get an id back
curl -X POST https://api.hotdata.dev/v1/databases \
  -H "Authorization: Bearer $HOTDATA_API_KEY" \
  -H "X-Workspace-Id: $HOTDATA_WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "nightly-rollup", "expires_at": "24h"}'

# => { "id": "dbid6lguax1dxn9y1xj5gxnameyywl", "default_catalog": "default", … }

Retain the returned id. Loads address it in the path; queries name it in the X-Database-Id header. Tokens are stored hashed and displayed once, so the value should be treated as unrecoverable and rotated by issuing a replacement.