# Call DeltaStream’s REST API

DeltaStream exposes a single **POST** endpoint for executing SQL statements:

```bash
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.

<figure><img src="https://1288764042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdbd9e6ZJodkgF1H6AVay%2Fuploads%2F1YpEwGpEBqYnmDfJ8NCq%2FScreenshot%202025-10-12%20at%2011.09.55%E2%80%AFAM.png?alt=media&#x26;token=48e48ff8-c85c-41d1-b61a-d9267f72e8e3" alt=""><figcaption></figcaption></figure>

***

### 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.

<figure><img src="https://1288764042-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fdbd9e6ZJodkgF1H6AVay%2Fuploads%2FU7BYlohIaZmvwCoaY5W0%2FScreenshot%202025-10-12%20at%2011.14.05%E2%80%AFAM.png?alt=media&#x26;token=8064a461-fd7f-4ba8-9eb2-8bfe44569ec3" alt=""><figcaption></figcaption></figure>

***

### 3) Make a request (recommended CURL patterns)

#### Use environment variables (safer)

```bash
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:

```bash
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**

```bash
$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)

```json
{
  "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)

```javascript
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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.deltastream.io/how-do-i.../call-deltastreams-rest-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.