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

# REST API

> Authenticate with Firebolt service accounts, discover account and user engine URLs, and understand query request limits.

> [!NOTE]
>
> This guide covers connections authenticated through `id.app.firebolt.io`, using Firebolt service accounts and account and user engine URLs. For engines deployed with the Firebolt Operator or Helm chart, see [Connect over HTTP](https://docs.firebolt.io/self-managed/connecting-over-http.md).

Use the Firebolt REST API to execute queries on engines programmatically. Learn how to use the API, including authentication, working with engines and executing queries. A service account is required to access the API. Learn about [managing programmatic access to Firebolt](https://docs.firebolt.io/managed-service/organization/service-accounts.md).

## Create a service account and associate it with a user

Create a service account with organization administrator privilege,
i.e., the service account property\_is\_organization\_admin\_ must be *true*.
Next, create a user with role privileges you would like to have the service account
and associate the service account with the user.

## Use tokens for authentication

To authenticate Firebolt using the service accounts with the properties
as described above via Firebolt’s REST API, send the following request
to receive an authentication token:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl -X POST --location 'https://id.app.firebolt.io/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'audience=https://api.firebolt.io' \
--data-urlencode "client_id=${service_account_id}" \
--data-urlencode "client_secret=${service_account_secret}"
```

where:

| Property | Data type | Description |
| :- | :- | :- |
| client\_id | TEXT | The service [account ID](https://docs.firebolt.io/managed-service/organization/service-accounts.md#get-a-service-account-id). |
| client\_secret | TEXT | The service [account secret](https://docs.firebolt.io/managed-service/organization/service-accounts.md#generate-a-secret). |

**Response**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "access_token":"access_token_value",
  "token_type":"Bearer",
  "expires_in":86400
}
```

In the previous example response, the following apply:

* The `access_token` is a unique token that authorizes your API requests that acts as a temporary key to access resources or perform actions. You can use this token to authenticate with Firebolt’s platform until it expires.
* The `token_type` is `Bearer`, which means that the access token must be included in an authorization header of your API requests using the format: `Authorization: Bearer <access_token>`.
* The token `expires_in` indicates the number of seconds until the token expires.

Use the returned access\_token to authenticate with Firebolt.

To run a query using the API, you must first obtain the URL of the engine you want to run on.

## Get the account gateway URL

Use the following endpoint to return the account gateway URL for `<account name>`.

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl https://api.app.firebolt.io/web/v3/account/<account name>/engineUrl \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <access token>'
```

**Example:** `https://api.app.firebolt.io/web/v3/account/my-account/engineUrl`

**Response**

```json theme={"theme":{"light":"css-variables","dark":"css-variables"}}
{
  "engineUrl":"<prefix>.api.us-east-1.app.firebolt.io"
}
```

You can use this URL for metadata queries (for example, looking up engine URLs in `information_schema.engines`) and for DDL that does not target a specific user engine.

## Get a user engine URL

Get a user engine URL by running the following query against the `information_schema.engines` table:

```sql theme={"theme":{"light":"css-variables","dark":"css-variables"}}
SELECT url 
FROM information_schema.engines 
WHERE engine_name='<engine_name>'
```

You can run the query using the account gateway URL with the following request:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl --location 'https://<account gateway URL>/query' \
--header 'Authorization: Bearer <access token>' \
--data 'SELECT url FROM information_schema.engines WHERE engine_name='\''my_engine'\'''
```

## Execute a query on a user engine

Use the following endpoint to run a query on a user engine:

```bash theme={"theme":{"light":"css-variables","dark":"css-variables"}}
curl --location 'https://<user engine URL>&database=<database name>' \
--header 'Authorization: Bearer <access token>' \
--data '<SQL query>'
```

where:

| Property | Data type | Description |
| :- | :- | :- |
| user engine URL | TEXT | The user engine URL ([retrieved here](#get-a-user-engine-url)) |
| database name | TEXT | The database to run the query |
| SQL query | TEXT | Any valid SQL query |

> [!NOTE]
>
> Queries are per request. To run multiple statement queries, separate queries each into one request.

## API limits

### Request size limits

The limits and retry behavior in this section apply to requests sent to the user engine URLs obtained through the account gateway as described in this guide.

Query requests to these user engines have a maximum body size of 40 MiB (41,943,040 bytes). A request whose body exceeds the limit is rejected with HTTP 413:

```
413: Request body is larger than configured limit of 41943040 bytes for queries to User Engines
```

Design requests to stay well below the limit.

**Retry threshold.** Independently of the request size limit, Firebolt keeps a copy of request bodies of up to 2 MiB (2,097,152 bytes) so that it can resend them. A request within that size is retried automatically after a transient failure, such as a connection error or a 502, 503, or 504 response from the engine, and is included in online upgrade verification. A larger request is sent to the engine once and:

* Is not retried. The first failure is returned to the client.
* Is not included in online upgrade verification.
* Is not redirected automatically if it must run on the account gateway URL rather than on a user engine. Send such requests to the account gateway URL directly.

Keep request bodies under 2 MiB. If a query carries a large literal list, for example a long `IN (...)` clause, load the values into a table and join against it instead of inlining them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.