Aiven REST API: Turn a SQL Query into an Endpoint

REST API · Aiven to an endpoint

Turn a Aiven SQL query into a REST API endpoint

Save a query in Query Builder, click New endpoint, and you have a URL at api.querystreams.com with its own key. The SQL runs read-only on the Agent that already sits with your Aiven database; the caller gets JSON or CSV and never sees the SQL, the schema or a password. Nothing to host, no port to open. About 90 seconds from a saved query, and the Free plan covers your first endpoint.

About 90 seconds from a saved query No server to host Credentials stay with you One key per caller, revoke anytime

What you’ll end up with

A URL at api.querystreams.com that returns the rows of your saved Aiven query as JSON or CSV to anyone holding a key, tested from the console in the portal before you share it. Like this:

{
  "city": "Seattle"
}

curl -X POST "https://api.querystreams.com/v1/endpoints/8f2c4d1e-6b3a-4f7e-9c21-5d0a7b3e2f19" \
  -H "X-API-Key: qsapi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"city": "Seattle"}'

{
  "columns": [ { "name": "customer_id", "type": "integer" }, { "name": "name", "type": "string" }, { "name": "city", "type": "string" } ],
  "rows": [
    { "customer_id": 1042, "name": "Northwind Traders", "city": "Seattle" },
    { "customer_id": 1057, "name": "Alpine Outfitters", "city": "Denver" },
    { "customer_id": 1063, "name": "Harbour Foods", "city": "Halifax" }
  ],
  "meta": { "row_count": 3, "agent_duration_ms": 41, "request_id": "req_7Hq2mKd9" }
}

Aiven holds your data in the cloud, run by its provider. Someone else wants a slice of it in their app, their dashboard or their script, and the usual answers all hand over too much: a database login that outlives the project, a nightly export that is stale by breakfast, or a small API server that somebody now has to run and patch. Query Streams makes the endpoint a saved query plus a key. The Agent that already sits with your Aiven service runs the query, api.querystreams.com checks the key and the rate limit, and the caller gets rows. The SQL, the schema and the credentials never leave your account.

What you’ll need

A Query Streams account

Every plan has the REST API. Free gives you one endpoint, two keys and 250 rows per call, which is enough to build this guide. Sign up at my.querystreams.com.

The Agent on any always-on computer, with the Aiven connection added

It only needs internet access.

A saved query in Query Builder

The endpoint wraps exactly one saved query. Write the SELECT, run it once, save it. Add a Dynamic Filter (a @variable in the WHERE clause) if callers should be able to filter.

Set it up in four steps

1. Save the query

   In Query Builder pick your Aiven connection, write the SELECT you want to publish and run it once so you can see the rows. Keep it to the columns the caller needs; the endpoint returns exactly what the query returns.

   Saved query · customers

   SELECT customer_id, name, city
   FROM public.customers
   ORDER BY name
   LIMIT 100;

   If callers should be able to filter, add a Dynamic Filter, for example WHERE city = @city. Each @variable becomes an API parameter in step 3. Click Save and give the query a name; that name becomes the endpoint’s display name.

2. Create the endpoint

   Open API in the top bar and click New endpoint. The wizard has four steps, Pick query, Configure, Lock params and Share. On Pick query, click the query you just saved; queries whose Agent is offline are greyed out. Click Next.

   Open API

   Shortcut. From Query Builder you can expose the open query directly; the wizard then starts at Configure with the query already chosen.

3. Configure and lock parameters

   On Configure the defaults are right for a first endpoint: Display name filled from the query, Lifespan Permanent (choose Expiring for a temporary share), Response mode Static (one JSON response; pick Streaming for results beyond your plan’s static row cap), Inner format JSON. Response mode and format are fixed once created, so decide them here. Click Next.

   On Lock params every Dynamic Filter in the query is listed. Leave the ones callers may set as Callable and give each a Query string name; tick Required if a call without it should fail. Pin a value the caller must not change with Locked, or a date scenario such as Start of month. Hidden keeps the query’s own default and rejects any attempt to set it. Click Next.

4. Share and get your key

   On Share you can invite People by email or add a Service key for a server or an automation tool, or skip both for now. Click Create & get my key. The success screen shows the endpoint URL and your key: a 49-character string starting qsapi_. Copy it. You can reveal it again later from the endpoint’s Sharing tab, so it is not lost if you close the screen.

   Click Send in the console to make the first call from the portal itself. The response pane shows Status, Time and Size, the Body tab shows the JSON, and the call appears on the Activity tab a few seconds later.

Call it from anywhere

Replace the endpoint id with yours from the console’s URL bar and qsapi_YOUR_KEY with your key. Callable parameters go in the query string on GET; here the saved query exposes city:

curl "https://api.querystreams.com/v1/endpoints/8f2c4d1e-6b3a-4f7e-9c21-5d0a7b3e2f19?city=Seattle" \
  -H "X-API-Key: qsapi_YOUR_KEY"

{
  "columns": [ { "name": "customer_id", "type": "integer" }, { "name": "name", "type": "string" }, { "name": "city", "type": "string" } ],
  "rows": [
    { "customer_id": 1042, "name": "Northwind Traders", "city": "Seattle" },
    { "customer_id": 1057, "name": "Alpine Outfitters", "city": "Denver" },
    { "customer_id": 1063, "name": "Harbour Foods", "city": "Halifax" }
  ],
  "meta": { "row_count": 3, "agent_duration_ms": 41, "request_id": "req_7Hq2mKd9" }
}

Rows come back as objects keyed by column name, with the column list and a meta block that tells you how many rows there are, whether the result was clipped, and the request id you can quote to support. The same call as a POST puts the parameters in a JSON body, which is the right choice for long lists of values:

curl -X POST "https://api.querystreams.com/v1/endpoints/8f2c4d1e-6b3a-4f7e-9c21-5d0a7b3e2f19" \
  -H "X-API-Key: qsapi_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"params": {"city": "Seattle"}}'

?format=csv

CSV instead of JSON, header row included. Accept: text/csv does the same. Streaming endpoints return NDJSON (one JSON object per line) with a final {"_summary": true, "row_count": N} line; check that last line.

?sample=true

At most five rows, not billed. Good for wiring up a client.

?compression=lz4

An LZ4-frame body for high-volume callers with a decoder; the Code tab has the decoder snippet per language. Plain gzip happens on its own when your client sends Accept-Encoding: gzip.

Authorization: Bearer qsapi_…

Accepted as an alias for X-API-Key. Use it from browser code.

Where it plugs in

What the plans allow

Every call also has a fixed 60-second query timeout and an 8 MiB response cap, and the bytes it returns count against your plan’s monthly data allowance, the same allowance the Excel and Google Sheets add-ins use. Free has one endpoint and 5 MB a month, which comfortably covers a small table called many times a day. See the pricing page for the allowances by plan.

Keeping it safe

When something doesn’t work

Every error body has the shape {"error": {"code": "…", "message": "…"}} and every response carries an X-QS-Request-Id header. Quote the id when you write to support.

Questions people ask

Related guides

• Connect Aiven to Claude with MCP
• Database REST API: Turn Any SQL Query into an Endpoint
• Microsoft SQL Server REST API
• PostgreSQL REST API
• MySQL REST API
• Snowflake REST API