Atlas API

Reading Data

# First-time API users: acquire the "public" tag (Atlas UI does this automatically)
curl -X POST https://your-domain.com/api/tags/acquire/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_name": "public"}'

# List available datasets
curl -H "X-API-Key: YOUR_API_KEY" https://your-domain.com/api/datasets/

# Search by name or description
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-domain.com/api/datasets/?search=bitcoin"

# Get data from a dataset
curl -H "X-API-Key: YOUR_API_KEY" \
  "https://your-domain.com/api/rows/?dataset=1&limit=100"

Creating Data

# 1. Create a dataset
curl -X POST https://your-domain.com/api/datasets/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my_btc_prices", "description": "Bitcoin hourly prices"}'

# 2. Insert data (use the returned dataset ID)
curl -X POST https://your-domain.com/api/rows/bulk_insert/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"dataset": 1, "rows": [
    {"timestamp": "2025-12-16T10:00:00Z", "values": {"price": 104500}},
    {"timestamp": "2025-12-16T11:00:00Z", "values": {"price": 104600}}
  ]}'

# 3. Share it by adding the "public" tag
curl -X POST https://your-domain.com/api/datasets/1/tags/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_name": "public"}'

curl -H "X-API-Key: YOUR_API_KEY" https://your-domain.com/api/datasets/

Check if the service is running and connected to the database.

{
  "status": "healthy",
  "time": "2025-12-16T10:30:00Z",
  "database": "connected"
}

List datasets with optional text search. The search parameter performs case-insensitive substring matching against the dataset name and description.

Parameter	Type	Description
search	string	Substring to match against name or description (case-insensitive)
limit	integer	Max results to return (default: 250)
offset	integer	Number of results to skip (for pagination)

Examples

# Search for datasets containing "bitcoin" in name or description
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/datasets/?search=bitcoin"

# Search for datasets with "price" anywhere in the text
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/datasets/?search=price"

# Get first 10 results
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/datasets/?search=market&limit=10"

Deprecated compatibility route; prefer unified discovery. Search datasets by metadata field values. Each query parameter (except limit and offset) is treated as a metadata filter with exact matching.

Parameter	Type	Description
{key}	any	Metadata field name and value (exact match)
limit	integer	Max results to return (default: 250)
offset	integer	Number of results to skip

Examples

# Find all datasets from Tiingo
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/datasets/search/?source=tiingo"

# Find BTC/USD data with 1-minute frequency
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/datasets/search/?ticker=btcusd&frequency=1min"

# Find premium-tier datasets
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/datasets/search/?tier=premium"

Legacy compatibility route (use dataset search for new integrations). Batch row-count and time-range summary for up to 100 datasets in one call. Powers dashboards that would otherwise need a per-dataset freshness probe. Results come from the hourly dataset_stats continuous aggregate.

Parameter	Type	Description
ids	integer list	Dataset ids, comma-separated (?ids=1,2,3), repeated (?ids=1&ids=2), or mixed. Required; maximum 100 per request.

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "dataset_id": 1,
      "row_count": 145230,
      "min_timestamp": "2026-01-01T00:00:00Z",
      "max_timestamp": "2026-01-12T18:30:00Z"
    }
  ]
}

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/datasets/stats/?ids=1,2,3"

Create a new dataset. You automatically become the owner.

{
  "name": "btc_hourly_ohlcv",
  "description": "Bitcoin hourly OHLCV candles from Tiingo",
  "metadata": {
    "source": "tiingo",
    "ticker": "btcusd",
    "frequency": "1h"
  }
}

{
  "id": 1,
  "name": "btc_hourly_ohlcv",
  "description": "Bitcoin hourly OHLCV candles from Tiingo",
  "metadata": {"source": "tiingo", "ticker": "btcusd", "frequency": "1h"},
  "columns": [],
  "created_at": "2025-12-16T10:30:00Z",
  "updated_at": "2025-12-16T10:30:00Z"
}

{
  "error": "dataset already exists",
  "details": {"name": "btc_hourly_ohlcv"}
}

Get a single dataset by ID. Requires read access (owner or matching tag).

Update dataset name, description, and metadata. Replaces all fields.

Permanently delete a dataset and all its data. This cannot be undone.

Merge new fields into existing metadata (partial update).

curl -X PATCH https://your-domain.com/api/datasets/1/metadata/ \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"version": "2.0"}'
# Merges with existing: {"source": "tiingo"} → {"source": "tiingo", "version": "2.0"}

Replace all metadata (full overwrite).

List all available tags in the system.

[
  {
    "id": 1,
    "name": "public",
    "description": "Publicly accessible datasets",
    "is_public": true,
    "metadata": {},
    "created_at": "2025-12-01T00:00:00Z",
    "updated_at": "2025-12-01T00:00:00Z"
  },
  {
    "id": 2,
    "name": "premium",
    "description": "Premium tier datasets",
    "is_public": false,
    "metadata": {},
    "created_at": "2025-12-01T00:00:00Z",
    "updated_at": "2025-12-01T00:00:00Z"
  }
]

Acquire a tag for yourself to gain access to datasets with that tag.

Acquire a Public Tag

curl -X POST https://your-domain.com/api/tags/acquire/ \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_name": "public"}'

Acquire a Private Tag (with secret)

curl -X POST https://your-domain.com/api/tags/acquire/ \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_name": "premium", "secret": "your-secret-key"}'

Check if you have access to a specific dataset.

{
  "dataset_id": 1,
  "require_write": false
}

{
  "has_access": true,
  "is_owner": false,
  "matching_tags": ["public"]
}

Get all tags assigned to a dataset.

Assign a tag to your dataset to grant read access to users with that tag.

curl -X POST https://your-domain.com/api/datasets/1/tags/ \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_name": "public"}'

# Or by tag ID:
curl -X POST https://your-domain.com/api/datasets/1/tags/ \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tag_id": 1}'

Remove a tag from your dataset. Users with only that tag will lose access.

List columns for a specific dataset.

Create a new column definition. Use this to document your schema for the Atlas UI.

{
  "dataset": 1,
  "name": "close_price",
  "dtype": "float"
}

Field	Type	Description
dataset	integer	Dataset ID this column belongs to
name	string	Column name (should match keys in row values)
dtype	string	float, int, or string

{
  "error": "column already exists for this dataset",
  "details": {"dataset_id": 1, "name": "close_price"}
}

Query one dataset with legacy pagination, or opt into grouped multi-dataset reads using datasets or dataset_names. All requests require read access.

Parameter	Type	Description
dataset	integer	Single dataset ID. Use this or dataset_name for the existing paginated response.
dataset_name	string	Single dataset name, as an alternative to dataset.
datasets	integer list	Bulk mode: comma-separated IDs or repeated parameters, up to 1,000 datasets.
dataset_names	string list	Bulk mode: comma-separated names or repeated parameters. Do not mix with other selectors.
start	datetime	Inclusive start timestamp (RFC 3339, for example 2026-01-01T00:00:00Z).
end	datetime	Inclusive end timestamp (RFC 3339). Bulk requests reject a start later than the end.
ordering	string	timestamp (ascending, default) or -timestamp (newest first). Applies within each dataset.
limit	integer	Single dataset: default 250, maximum 10,000; 0 or values above 10,000 reset to 250. Bulk: positive per-dataset limit, default 10; dataset count × limit must not exceed 10,000.
offset	integer	Single dataset only: number of rows to skip (default 0, maximum 2,147,483,647). Rejected in bulk mode, even when 0.
after	datetime	Single raw dataset only: timestamp cursor, exclusive in the requested ordering direction, used instead of offset. Currently ignored for single-dataset aggregates. Rejected in bulk mode.
count	boolean	Single dataset only: true asks for a total on any page, false skips it even on the first page. When omitted, only the first page reports a total: offset 0, and for raw rows no after cursor (aggregates ignore after). Ignored in bulk mode.
resolution	string	Omit for original provider rows without a default time window. Explicit raw also returns original rows; 5m, 1h, and 1d return aggregated OHLCV candles.

Example

curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/rows/?dataset=1&start=2025-12-01T00:00:00Z&end=2025-12-16T00:00:00Z&ordering=-timestamp&limit=100"

Time windows and row formats

When resolution is explicitly supplied, maximum windows are 24 hours for raw, 7 days for 5m, 90 days for 1h, and unlimited for 1d. For bounded resolutions, omitting both timestamps selects the most recent maximum window; supplying only one timestamp derives the other using that window. A larger explicit window is rejected. Omitting resolution preserves the legacy unbounded time-window behavior.

Raw rows contain id, dataset_id, timestamp, values, and created_at. Aggregated rows contain dataset_id, timestamp (bucket time), open, high, low, close, volume, and count (source row count). Existing aggregation behavior is unchanged; this endpoint does not add a completed-candle-only guarantee.

Single-dataset responses retain {"count": ..., "next": ..., "previous": ..., "results": [...]}. count is -1 when the total is unknown: the page did not ask for one (see count above), counting took longer than two seconds, a ranged count passed 100,000, the dataset has not been measured yet, or its metadata snapshot could not be read. Raw rows without start, end or resolution report the dataset's row count from the metadata snapshot (never less than the rows up to the end of a non-empty page). The snapshot lags new rows by minutes, and longer while historical backfills are being picked up, so this total is approximate. With a time range (including the default window of an explicit resolution=raw), raw rows count the range up to 100,000 rows; aggregates count their buckets up to 100,000. Only an exact total (a ranged or aggregate count within the cap) can end next: with one, next is omitted once the page reaches the total. With an approximate or unknown total, a full page always links to the next one and a short page is the last. To page through a large range, prefer the after cursor (raw rows) over a growing offset; cursor pages have no previous link.

Multiple Datasets — Recent Raw Candles

In bulk aggregate responses, unavailable OHLCV values are returned as JSON null, not zero; such values do not fail the request. Raw rows and single-dataset responses are unchanged.

Fetch the newest ten original provider rows per asset in one HTTP call. For one-minute provider candles, omit resolution; resolution=5m would aggregate into five-minute candles instead. Ten returned rows may span more than ten minutes when data has gaps.

# By ID
curl -G -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/rows/" \
  --data-urlencode "datasets=123,456" \
  --data-urlencode "limit=10" \
  --data-urlencode "ordering=-timestamp"

# By name (same response shape, with resolved dataset IDs)
curl -G -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/rows/" \
  --data-urlencode "dataset_names=btc_usd_1m,eth_usd_1m" \
  --data-urlencode "limit=10" \
  --data-urlencode "ordering=-timestamp"

Bulk requests must use exactly one plural selector, without dataset or dataset_name. Duplicate datasets, empty selectors, invalid IDs, and offset/after are rejected with HTTP 400. Shared time filters, ordering, and resolution apply independently to each dataset.

A single plural parameter is parsed as a CSV list. When the parameter appears more than once, each value is one literal ID or name: dataset_names=btc_usd_1m&dataset_names=eth_usd_1m. Do not combine repeated parameters with comma-separated lists. For a name containing a comma, use repeated literal name parameters, or CSV-quote the name in a single parameter (for example, --data-urlencode 'dataset_names="btc,usd"'). URL-encode names and other query values.

Maximum 1,000 datasets and 10,000 requested rows, calculated as dataset count × per-dataset limit, regardless of how many rows actually exist. Thus 1,000 datasets × 10 rows is valid; 1,000 × 11 is HTTP 400. For 200 assets, requesting ten rows each returns at most 2,000 rows. An omitted bulk limit defaults to 10.

{
  "dataset_count": 2,
  "row_count": 1,
  "datasets": [
    {
      "dataset_id": 123,
      "rows": [
        {
          "id": 1001,
          "dataset_id": 123,
          "timestamp": "2026-01-01T12:00:00Z",
          "values": {"open": 100, "high": 105, "low": 99, "close": 103, "volume": 1200},
          "created_at": "2026-01-01T12:01:00Z"
        }
      ]
    },
    {"dataset_id": 456, "rows": []}
  ]
}

Groups follow request order and include empty datasets. row_count is the actual total returned, not a historical count. Bulk responses have no pagination links or historical totals. Names resolve to IDs; all datasets must exist and be readable before any rows are returned. A missing dataset returns HTTP 404, denied access HTTP 403, and a query failure fails the entire response rather than returning partial results. Single-dataset interfaces remain unchanged.

Insert a single row of data.

{
  "dataset": 1,
  "timestamp": "2025-12-16T10:00:00Z",
  "values": {
    "open": 104500.00,
    "high": 104800.00,
    "low": 104200.00,
    "close": 104600.00,
    "volume": 1234567
  }
}

Insert or update rows using the PostgreSQL COPY fast path. Existing rows with the same dataset and timestamp are updated. The endpoint accepts either the original single-dataset body or a multi-dataset body.

Single Dataset

{
  "dataset": 1,
  "rows": [
    {
      "timestamp": "2025-12-16T10:00:00Z",
      "values": {"open": 104500, "close": 104600}
    },
    {
      "timestamp": "2025-12-16T11:00:00Z",
      "values": {"open": 104600, "close": 104700}
    }
  ]
}

{
  "inserted": 2,
  "total": 2
}

Multiple Datasets

Use datasets to update hundreds of datasets in one HTTP request. Each item must specify exactly one of dataset or dataset_name. The complete request is validated and written atomically: if any dataset is missing, unauthorized, or invalid, no rows are changed.

curl -X POST https://your-domain.com/api/rows/bulk_insert/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasets": [
      {
        "dataset": 1,
        "rows": [
          {"timestamp": "2025-12-16T10:00:00Z", "values": {"price": 104500}}
        ]
      },
      {
        "dataset_name": "eth_usd_1m",
        "rows": [
          {"timestamp": "2025-12-16T10:00:00Z", "values": {"price": 3890}}
        ]
      }
    ]
  }'

{
  "inserted": 2,
  "total": 2,
  "datasets": [
    {"dataset": 1, "inserted": 1, "total": 1},
    {"dataset": 2, "inserted": 1, "total": 1}
  ]
}

Download all data from a dataset in CSV or JSON format.

Parameter	Type	Description
dataset	integer	Dataset ID (required)
output	string	json (default) or csv
start	datetime	Optional start timestamp
end	datetime	Optional end timestamp

# Download as CSV
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/rows/bulk_download/?dataset=1&output=csv" \
  > data.csv

# Download as JSON
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/rows/bulk_download/?dataset=1&output=json" \
  > data.json

Bulk download recent data as NDJSON (newline-delimited JSON). Memory-efficient for large datasets.

# Download most recent 1000 rows
curl -H "X-API-Key: YOUR_KEY" \
  "https://your-domain.com/api/rows/live/?dataset=1&limit=1000"

# Output: one JSON object per line
# {"timestamp":"2025-12-16T10:00:00Z","close":104600}
# {"timestamp":"2025-12-16T11:00:00Z","close":104700}

Real-time Server-Sent Events (SSE) stream. Connection stays open and pushes new data as it arrives.

Parameter	Type	Description
dataset	integer	Dataset ID (required)
poll_interval	integer	Seconds between checks for new data (default: 2)

Event Types

• connected - Initial connection established
• data - New data point received
• heartbeat - Keepalive (no new data)
• error - Query error occurred

# Connect to real-time stream
curl -H "X-API-Key: YOUR_KEY" \
  -H "Accept: text/event-stream" \
  "https://your-domain.com/api/rows/stream/?dataset=1&poll_interval=2"

# Output (connection stays open):
# event: connected
# data: {"dataset_id":1,"message":"Connected to real-time stream"}
#
# event: data
# data: {"timestamp":"2025-12-16T10:00:00Z","close":104600}
#
# event: heartbeat
# data: {"timestamp":"2025-12-16T10:00:02Z"}