Query

Run a read-only SQL query

POST https://api.rewind.rest/v1/query

Executes a single read-only SELECT (or WITH … SELECT) statement against the Rewind database and returns column names plus array-of-array row tuples. Gated server-side: writes, DDL, multi-statement input, and access to secret tables are rejected. A LIMIT is enforced automatically (200 default, 500 max). Fetch GET /v1/schema first for the annotated table list.

Authorization

Authorizationheaderstringrequired

API key. Read keys (rw_live_...) access GET endpoints. Admin keys (rw_admin_...) access all endpoints.

Body

sqlbodystringrequired

A single read-only SELECT (or WITH … SELECT) statement. A LIMIT is applied automatically (200 default, 500 max).

Response

application/json

Query results as column names plus row tuples

columnsarray of stringrequired

rowsarray of array of objectrequired

row_countintegerrequired

truncatedbooleanrequired

True when rows were dropped to fit the response ceiling.

integrationstringrequired

The single upstream service the queried tables belong to (lastfm, strava, discogs, …), or null when the query spans several or reads only shared tables. Renderers use it to tint a single-series chart in that service’s colour.

cURL

curl -X POST 'https://api.rewind.rest/v1/query' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{"sql": "SELECT strftime('%Y', scrobbled_at) AS year, count(*) AS plays FROM lastfm_scrobbles GROUP BY year ORDER BY year"}'

200

{
  "columns": [
    "year",
    "plays"
  ],
  "rows": [
    [
      "2024",
      18234
    ],
    [
      "2025",
      21012
    ]
  ],
  "row_count": 2,
  "truncated": false,
  "integration": "lastfm"
}