> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brightstack.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced

> Advanced usage with raw API calls

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

```http theme={null}
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](https://duckdb.org/docs/stable/sql/introduction.html) 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](https://duckdb.org/docs/stable/sql/data_types/overview.html) 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:

```ts theme={null}
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);
```