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. Another database's catalog 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.

Sharing a catalog

A database's default catalog is created with it and removed with it, but it is not sealed off: attaching it to another database through POST /v1/databases/{database_id}/catalogs makes its tables visible there, and it can be attached to as many databases as you need, at the same time. That is how one query reads across two databases.

A reference dataset is loaded into a database once and attached wherever it is needed; each database joins it against its own local tables. To attach, send the source's default_connection_id as the connection_id in the request body. Inside the attaching database the catalog answers to the alias you pass, or to the source's own catalog name when you pass none.

That name has to be free: it may not be default or another reserved name, may not be the attaching database's own default catalog name, may not be the source's own name given as an alias, and may not collide with an existing attachment. In practice this means a source that kept the stock default catalog name needs an alias — two databases created without a catalog name cannot attach unaliased.

Three properties are worth knowing before you depend on one:

• Read-only. Loads always target a database's own default catalog; attaching never makes another database writable.
• Not transitive. A database sees the catalog it attached, not the catalogs that one has attached in turn.
• The source is pinned, until it expires. Deleting a database — singly or as part of a bulk batch — is refused while another database attaches its catalog; detach there first. Once its expires_at has passed, it can be deleted regardless, and the attaching database loses the catalog: queries there keep working, but the attached tables are gone. Check the date before building on one.

Detaching withdraws visibility rather than deleting data, and deleting a database removes the attachments it holds while leaving the catalogs behind them 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",
#      "default_connection_id": "connu6ho8mseuv8rvsk15anzkmpdsm", … }

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.

Further reading

• Push Data — the loading model, upload sequence, and load modes.
• Pull Data — ingesting from sources you connect.
• API Reference — request and response shapes, field by field.