Call DeltaStream’s REST API

This page describes how you can use DeltaStream's REST API from your applications to submit statements and run queries.

DeltaStream exposes a single POST endpoint for executing SQL statements:

POST https://<your-org-endpoint>/v2/statements
Content-Type: application/json
Authorization: Bearer <API_TOKEN>
Body: {"statement": "<DeltaStream SQL>"}

Some statements return rows (e.g., SELECT), others return only acknowledgements (e.g., CREATE MATERIALIZED VIEW). The response is JSON and easy to parse.

---

1) Create an API token

1. In the DeltaStream web UI, go to Integration → API Tokens.

2. Click Create, give the token a name, choose a Role (this controls permissions), and click Create again.

3. Copy the token once and store it securely (you won’t be able to view it again).

Tip: Use the least-privileged role that still lets your statements succeed.

---

2) Find your API endpoint

In the DeltaStream UI, click the ? (Help) icon (bottom-left). Copy the API ENDPOINT for your org. See the screenshot below for details.

---

3) Make a request (recommended CURL patterns)

Use environment variables (safer)

export DS_ENDPOINT="https://api-<org-code>.deltastream.io/v2/statements"
export DS_TOKEN="<your-api-token>"

# Example: query a materialized view for a specific passenger
curl -s "$DS_ENDPOINT" \
  -H "Authorization: Bearer $DS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statement":"SELECT * FROM flightdb.public.disrupted_premium_passengers WHERE passenger_id = '\''PASS-2451'\'';"}' | jq

Why the funny quoting? Inside a single-quoted bash string, use '\'' to embed a single quote in SQL. If you don’t like that, use a heredoc:

read -r -d '' SQL <<'SQL'
SELECT *
FROM flightdb.public.disrupted_premium_passengers
WHERE passenger_id = 'PASS-2451';
SQL

curl -s "$DS_ENDPOINT" \
  -H "Authorization: Bearer $DS_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"statement\":\"$SQL\"}" | jq

Windows PowerShell

$DS_ENDPOINT = "https://api-<org-code>.deltastream.io/v2/statements"
$DS_TOKEN    = "<your-api-token>"
$SQL         = @"
SELECT *
FROM flightdb.public.disrupted_premium_passengers
WHERE passenger_id = 'PASS-2451';
"@

$Body = @{ statement = $SQL } | ConvertTo-Json -Compress
Invoke-RestMethod -Method Post -Uri $DS_ENDPOINT -Headers @{ Authorization = "Bearer $DS_TOKEN" } -ContentType "application/json" -Body $Body

---

Sample JSON response (trimmed)

{
  "createdOn": 1760293498,
  "data": [
    [
      "PASS-2451",
      "Mary Smith",
      "GOLD",
      "UA387",
      "DELAYED",
      "JFK",
      "ATL",
      "2025-10-12 02:41:12.828",
      "AISLE"
    ]
  ],
  "metadata": {
    "columns": [
      {"name":"passenger_id","nullable":false,"type":"VARCHAR"},
      {"name":"full_name","nullable":false,"type":"VARCHAR"},
      {"name":"loyalty_tier","nullable":false,"type":"VARCHAR"},
      {"name":"flight_id","nullable":false,"type":"VARCHAR"},
      {"name":"flight_status","nullable":false,"type":"VARCHAR"},
      {"name":"origin","nullable":false,"type":"VARCHAR"},
      {"name":"destination","nullable":false,"type":"VARCHAR"},
      {"name":"disruption_timestamp","nullable":false,"type":"TIMESTAMP"},
      {"name":"seating_preference","nullable":false,"type":"VARCHAR"}
    ],
    "context": {
      "databaseName":"Proactivecsa",
      "organizationID":"019718d7-1860-7f76-833d-1b0237282b6a",
      "roleName":"sysadmin",
      "schemaName":"public",
      "storeName":"KafkaCluster1"
    },
    "encoding":"json",
    "partitionInfo":[{"rowCount":1}]
  },
  "sqlState": "00000",
  "statementID": "0199d9ab-2d72-7841-8d02-c0ca23a27c04"
}

How to read this

• data: array of rows (each row is an array aligned to metadata.columns).

• metadata.columns: names, types, and nullability for each column in order.

• sqlState: SQL status code (00000 indicates success).

• statementID: server-side identifier for auditing/debugging.

• createdOn: request processing timestamp (epoch seconds).

If your statement doesn’t return rows (e.g., CREATE MATERIALIZED VIEW, INSERT, REFRESH), data may be empty while sqlState still indicates success.

---

Common pitfalls & fixes

• 401/403: invalid/missing token or insufficient role permissions. Regenerate or change role.

• 400: malformed JSON (check quoting) or invalid SQL.

• Wrong endpoint: ensure you’re hitting .../v2/statements on your org’s API domain.

• Quoting issues: prefer heredocs or use the environment-variable pattern above.

---

Quick JS example (for agents/actions)

async function runStatement(sql) {
  const res = await fetch("https://api-<org-code>.deltastream.io/v2/statements", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.DS_TOKEN}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ statement: sql })
  });

  if (!res.ok) {
    const err = await res.text();
    throw new Error(`DeltaStream ${res.status}: ${err}`);
  }
  const json = await res.json();
  // map rows to objects using metadata.columns
  const cols = json.metadata.columns.map(c => c.name);
  const rows = (json.data || []).map(r => Object.fromEntries(r.map((v,i) => [cols[i], v])));
  return { rows, meta: json.metadata, sqlState: json.sqlState, statementID: json.statementID };
}

---

Security notes

• Never hard-code tokens in code or docs. Use env vars / secret managers.

• Rotate any token that was exposed publicly.

• Always use HTTPS.

• Scope tokens to the minimal role needed.

---

TL;DR

1. Create a token → 2) copy your org’s API endpoint → 3) POST /v2/statements with {"statement":"<SQL>"} and a Bearer token. That’s it.