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

> Learn about using the Firebolt API to interact with Firebolt.

# REST API

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](/guides/managing-your-organization/service-accounts).

## 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":"github-light","dark":"github-dark"}}
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](/guides/managing-your-organization/service-accounts#get-a-service-account-id). |
| client\_secret | TEXT      | The service [account secret](/guides/managing-your-organization/service-accounts#generate-a-secret).    |

**Response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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. Queries can be run against any engine in the account, including the system engine.

## Get the system engine URL

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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":"github-light","dark":"github-dark"}}
{
  "engineUrl":"<prefix>.api.us-east-1.app.firebolt.io"
}
```

## Execute a query on the system engine

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location 'https://<system engine URL>' \
--header 'Authorization: Bearer <access token>' \
--data '<SQL query>'
```

where:

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

## 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":"github-light","dark":"github-dark"}}
SELECT url 
FROM information_schema.engines 
WHERE engine_name='<engine_name>'
```

You can run the query on the system engine using the API with the following request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl --location 'https://<system engine URL>/query' \
--header 'Authorization: Bearer <access token>' \
--data 'SELECT * 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":"github-light","dark":"github-dark"}}
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.
</Note>

### OpenAPI spec

For a full definition of the query API, see the [OpenAPI spec](https://github.com/firebolt-db/openapi).

## API limits

### Request Size Limits

By default, Firebolt enforces request size limits of 2 MiB for User Engines, and 32 KiB for the System Engine. If you exceed these limits, you will get an error like:

```
413: Request body is larger than configured limit of 20971520 bytes. Please contact support if you need to send larger queries to support your workload
```

These limits are configurable, so please contact our support team if they are insufficient for your use-case.

**Note**: overriding these limits will disable the following features for large requests:

* Requests above 2 MiB will not be retried internally after transient network errors.
* Requests above 2 MiB will not be included in online upgrade verification.

### Rate-limiting

For information about rate-limits on System Engines, see [here](/guides/operate-engines/system-engine#rate-limits-for-system-engines).

There are no rate-limits on User Engines.