# Core Concepts

Source: https://www.hotdata.dev/docs/core-concepts
Site index: https://www.hotdata.dev/llms.txt

The foundations of every Hotdata integration: the object model includes workspaces, databases, catalogs, tables and authentication. Continue to [Push Data](/docs/push-data) (your systems send the data) or [Pull Data](/docs/pull-data) (Hotdata fetches it). Field-by-field detail is in the [API reference](/docs/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.

**Workspace** (`work…`) — 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.

**Database** (`dbid…`) — 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.

> **Not part of the model** — There are no projects, environments, or teams, and no per-workspace roles. Access is granted at the organization level, and a token carries read or read-write permission plus an optional list of the workspaces it may address. The workspace is the isolation boundary; the database is the lightweight, short-lived scope within it.

## 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.

```bash
# 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.

> **Client libraries** — Integrations may be built directly against the HTTP API or through a maintained SDK — Hotdata publishes clients for **Python** and **Rust**. Both handle authentication and encapsulate the upload sequence described in [Push Data](/docs/push-data). The underlying surface is identical, so the material here applies in either case.

## Further reading

- [Push Data](/docs/push-data) — the loading model, upload sequence, and load modes.
- [Pull Data](/docs/pull-data) — ingesting from sources you connect.
- [API Reference](/docs/api-reference) — request and response shapes, field by field.