​
Advanced Usage

Using the CLI is great for maintenance, quick tests, and one-off tasks, but brightstack really shines when you integrate it with your applications. You can do that by using:
  • HTTP API: integrate directly with the Data API.
  • SDK: use our JavaScript client library for a more convenient experience.
Let’s explore advanced use cases using the raw HTTP API!

​
Making API Calls

The Data API is simple to use! This is what a request might look like: 
GET /v1/api-keys
Authorization: Bearer <API_KEY_SECRET>
Content-Type: application/json
From now on please assume that we are using the Authorization and Content-Type headers as described above unless mentioned otherwise.

​
Sessions

By default, running SQL queries is a stateless process. Sessions provide a stateful mechanism to make queries. Sessions can only execute one query at a time, so you must create a pool of them if you want to make multiple stateful queries in parallel. Using sessions has several benefits. On top of queries being a bit faster, you don’t have to type USE <database> in every query! You can create a Session like this: 
POST /v1/sql/connect

{
  "engine": <ENGINE_ID_OR_NAME>
}

HTTP 201 Created

{
  "data": {
    "id": "sess_123abc",
    "engineId": "eng_456def",
    "createdAt": "2025-03-20T15:30:00Z",
    "lastUsedAt": "2025-03-20T15:35:00Z",
    "status": "idle"
  }
}
You can now use this session ID when making SQL queries! You can also disconnect from a session. This is not necessary most of the time, as sessions that have been idle for a long time are automatically purged. 
POST /v1/sql/disconnect

{
  "engine": <ENGINE_ID_OR_NAME>,
  "session": <SESSION_ID>
}

HTTP 204 No Content

​
Raw API SQL Queries

Our Data Engine is powered by a DuckDB core, so most of DuckDB’s SQL dialect will work out of the box. Please remember that session is optional! 
POST /v1/sql
{
  "statement": "SELECT COUNT(*) FROM hits;",
  "session": "sess_123abc"
}

HTTP 200 OK

{
  "data": {
    "id": "result_abc123",
    "engineId": "eng_456def",
    "sessionId": "sess_123abc",
    "createdAt": "2025-01-20T15:30:00Z",
    "status": "success",
    "columns": [
      {
        "name": "count_star()",
        "type": {
          "id": "BIGINT"
        }
      }
    ],
    "data": [
      ["42"]
    ],
    "metadata": {
      "page": 1,
      "pageCount": 1,
      "rowCount": 1,
      "executionTime": 1.0
    }
  }
}
Here is a reference of the data types we support. IMPORTANT: JSON cannot represent complex data types well (ex: BIGINT), so all row data is serialized as strings (with the exception of null). You can use the type information from the matching column in order to parse this correctly using your preferred programming language’s mechanisms. We are working on native SDKs to make this process more fun.

​
Raw JavaScript Example

Here is an example of making a simple SQL query using plain JavaScript: 
const engineName = "dev";
const statement = "SELECT 1;";

const request = await fetch("https://api.brightstack.ai/v1/sql", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${process.env.BRIGHTSTACK_API_KEY}`,
  },
  body: JSON.stringify({
    engine: engineName,
    statement,
  }),
});

const result = await request.json();
console.log(result.data);