TimesinkDB Living REST API Reference

1. Regional Endpoints & Base URLs

TimesinkDB runs storage engines directly against local NVMe volumes within regional compute clusters. Each database is provisioned in a dedicated geographic cloud region for single-digit millisecond latency and clear data residency. Client applications direct requests to the regional base URL corresponding to their database location:

2. Authentication, Credentials & mTLS

TimesinkDB authenticates requests via Bearer tokens passed in the standard HTTP Authorization header (or query parameter for embeds), or via mutual TLS client certificates on dedicated mTLS hostnames:

3. Telemetry Metering & Capacity Pooling

TimesinkDB charges $0.00 in write API fees (no HTTP transaction fees, indexing surcharges, or request units). Usage reflects pure tiered NVMe storage, outbound query egress, and parallel query workers:

TimesinkDB operates over standard HTTPS with pure UTF-8 JSON. Standard fetch() or your favorite HTTP client is all you need:

const TSDB_URL = "https://fra1.timesinkdb.com/databases/42";
const TSDB_TOKEN = process.env.TIMESINKDB_KEY;

// 1. Ingest telemetry point
await fetch(`${TSDB_URL}/series/services.auth.latency_ms`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${TSDB_TOKEN}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ value: 14.8, route: "/login", status: 200 })
});

// 2. Query downsampled 1-hour average buckets
const res = await fetch(`${TSDB_URL}/query?seriesKey=services.auth.latency_ms&from=-24h&interval=1h&fn=avg`, {
  headers: { "Authorization": `Bearer ${TSDB_TOKEN}` }
});
const { buckets } = await res.json();

import httpx

TSDB_URL = "https://fra1.timesinkdb.com/databases/42"
HEADERS = {"Authorization": "Bearer sec_live_..."}

with httpx.Client(base_url=TSDB_URL, headers=HEADERS) as client:
    # 1. Ingest numeric telemetry
    client.post("/series/fleet.vehicle_99.speed", json={
        "speed_kmh": 104.2,
        "battery_pct": 78.5
    })

    # 2. Query analytical aggregates
    resp = client.get("/query", params={
        "seriesKey": "fleet.vehicle_99.speed",
        "from": "-6h",
        "interval": "15m",
        "fn": "avg"
    })
    print(resp.json())

using System.Net.Http.Json;

using var http = new HttpClient {
    BaseAddress = new Uri("https://fra1.timesinkdb.com/databases/42/")
};
http.DefaultRequestHeaders.Authorization = new("Bearer", "sec_live_...");

// 1. Post telemetry point
await http.PostAsJsonAsync("series/iot.sensor_12.temperature", new {
    celsius = 23.4,
    humidity = 45.1
});

// 2. Query downsampled vector
var query = await http.GetFromJsonAsync<QueryResponse>(
    "query?seriesKey=iot.sensor_12.temperature&from=-12h&interval=30m&fn=avg"
);

# 1. Ingest telemetry point
curl -X POST https://fra1.timesinkdb.com/databases/42/series/api.requests \
  -H "Authorization: Bearer sec_live_..." \
  -H "Content-Type: application/json" \
  -d '{"duration_ms": 124.5, "status": 200}'

# 2. Query downsampled averages
curl -G https://fra1.timesinkdb.com/databases/42/query \
  -H "Authorization: Bearer sec_live_..." \
  --data-urlencode "seriesKey=api.requests" \
  --data-urlencode "from=-24h" \
  --data-urlencode "interval=15m" \
  --data-urlencode "fn=avg"

Test TimesinkDB HTTP requests directly in your browser. Inspect wire payloads, simulated response round-trips, and formatted JSON responses.

Authorization: Bearer sec_live_09f4b7a7019842a...
Content-Type: application/json

[
  {
    "seriesKey": "fleet.sensor-a.temp",
    "ts": 1788624900000,
    "value": 42.8
  },
  {
    "seriesKey": "fleet.sensor-b.speed",
    "ts": 1788624900000,
    "value": 88.5
  }
]

content-type: application/json; charset=utf-8

{
  "status": "accepted",
  "ingestedBytes": 32,
  "pointsIngested": 2
}

High-performance scoped ingestion endpoint supporting versatile structured extraction and raw event storage modes:

• extract (Default): Nested JSON numeric properties are flattened into dot-delimited columnar metric streams.
• blob: Stores the entire raw UTF-8 JSON payload verbatim as an immutable event record under the series key.
• blobArray: Treats the request body JSON array as multiple distinct blob events.
• both: Dual persistence. Flattens numeric fields while preserving raw JSON payload verbatim.
• bothArray: Applies dual persistence across each item in a JSON array.

{
  "ts": "2026-09-05T19:15:00.000Z",
  "usage": 84.2,
  "core": {
    "temp": 68.4,
    "frequency": 3400
  }
}

{
  "status": "accepted",
  "ingestedBytes": 48,
  "pointsIngested": 3
}

High-throughput batch ingest endpoint for dispatchers, edge aggregators, and proxy workers. Accepts a top-level JSON array of envelope items without artificial object wrappers (up to 5,000 items per request).

[
  {
    "seriesKey": "fleet.sensor-a",
    "ts": 1788624900000,
    "value": { "temp": 21.8, "humidity": 45.2 }
  },
  {
    "seriesKey": "fleet.sensor-b",
    "ts": "2026-09-08T00:15:00Z",
    "value": { "temp": 23.1, "pressure": 101.3 }
  }
]

{
  "status": "accepted",
  "ingestedBytes": 64,
  "pointsIngested": 4
}

TimesinkDB guarantees that telemetry ingestion always succeeds as long as the payload is valid JSON. Upstream systems (IoT firmware, Kubernetes exporters, Stripe webhooks) never face rejection due to unconventional property naming.

Turnkey webhook adapter that accepts raw HTTP webhook deliveries directly from third-party platforms (Stripe, GitHub, Shopify, Clerk) with zero intermediate glue code, lambdas, or queues. TimesinkDB verifies HMAC signatures at the edge and handles duplicate deliveries via monotonic Last-Write-Wins deduplication.

Lists registered series keys and their assigned storage types for the database, or retrieves specific series data directly via the key query parameter.

{
  "count": 2,
  "maxSeries": 65000,
  "series": [
    { "seriesKey": "fleet.sensor-a.temp", "type": "numeric" },
    { "seriesKey": "fleet.audit.logs", "type": "blob" }
  ]
}

Canonical endpoint for retrieving time-series data and multi-representation projections. Automatically distinguishes between instant constant-time latest point lookups and temporal range queries based on parameter presence:

• O(1) Latest Point Retrieval (Default when from is omitted): Returns the most recent point in sub-millisecond time.
• Chronological Range Query (When from is specified): Streams historical records over the specified time range.
• Multi-Representation Projections: Append an extension (.svg, .html, .csv, .json) to render directly.

{
  "seriesKey": "fleet.sensor-a.temp",
  "type": "numeric",
  "ts": 1788624900000,
  "value": 21.8
}

{
  "seriesKey": "fleet.sensor-a.temp",
  "count": 2,
  "points": [
    { "ts": 1788624900000, "value": 21.8 },
    { "ts": 1788621300000, "value": 21.2 }
  ]
}

Executes hardware-accelerated downsampling, multi-series joins, and mathematical expressions across raw points. Deduplication is resolved dynamically over matching series chunks.

{
  "range": { "from": "-1h", "to": "now" },
  "interval": "15m",
  "queries": [
    {
      "id": "q1",
      "seriesKey": "fleet.*.temp",
      "field": "celsius",
      "fn": "avg"
    }
  ]
}

{
  "interval": "15m",
  "timestamps": [
    1788620400000,
    1788621300000
  ],
  "results": {
    "q1": {
      "values": [23.4, 24.1]
    }
  }
}

GET /databases/42/query?seriesKey=fleet.*.temp&from=-1h&to=now&interval=15m&fn=avg

Analytical queries can be projected directly into turnkey interactive visualizations or tabular export streams for Notion, GitHub READMEs, internal admin dashboards, and spreadsheet workflows.

Inspects (GET) or configures (PUT) granular retention lifetimes per series pattern at day granularity (e.g. 30d, 365d). Default infinite retention preserves data until manually purged. Rules run daily in the background and apply retroactively without locks.

{
  "rules": [
    { "pattern": "fleet.ephemeral.*", "retention": "30d" },
    { "pattern": "fleet.audit.*", "retention": "365d" }
  ]
}

Database lifecycle management, capacity partitioning, and API key generation are coordinated by the central TimesinkDB control plane.

curl -i https://fra1.timesinkdb.com/ping

Hardware-enforced guardrails and architectural boundaries designed to guarantee deterministic single-digit millisecond latency:

Unauthenticated operational probes used by load balancers, container orchestrators, and latency checkers.

• GET /healthz: Liveness probe returning 200 OK if API host process is alive.
• GET /ready: Readiness probe returning 200 OK if instance manager is ready to serve traffic (or 503 during shutdown).
• GET /ping: Minimal overhead latency ping returning plain text pong.