> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.sigmacomputing.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.sigmacomputing.com/_mcp/server.

# Get started with the Sigma REST API

The Sigma REST API lets you programmatically administer and interact with the powerful analytics in Sigma.

Using the available API endpoints, you can programmatically do any the following and more:

* Perform onboarding and offboarding of users.
* Manage account types for users and permissions for workbooks and reports.
* Export data from specific workbooks.
* Materialize data elements in a workbook.
* Identify input tables in use in your organization.
* Create and manage user attributes for row-level-security.

For assistance with the API, contact [Sigma Support](/docs/sigma-support).

## About the API

The Sigma API is built around REST principles, leveraging the <a href="https://swagger.io/specification/" target="_blank">OpenAPI specification</a>. It is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. It uses built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients.

It supports cross-origin resource sharing, allowing you to interact securely with the API from a client-side web application, although you should never expose your secret API key in any public website's client-side code.

Endpoints accept JSON in the request body and can include JSON in the response body.

Responses from the [Download an exported file](/reference/download-query) endpoint for files requested with the [Export data from a workbook](/reference/export-workbook) endpoint can include CSV, XLSX, PDF, PNG, and JSON formats as the response body.

Use of the API is governed by the legal agreement governing your use of the Sigma Service.

## Prerequisites

* [Identify the URL to use](#identify-your-api-request-url) for your API calls.
* [Generate API client ID and secret](/reference/generate-client-credentials). You can also have a user assigned the Admin [account type](/docs/create-and-manage-account-types) to generate credentials for you.
* [Use your credentials to generate a bearer token](/reference/post-token).

### Identify your API request URL

The URL you use to send API requests depends on the [cloud your Sigma organization is hosted on](/docs/region-warehouse-and-feature-support).

View your **Base URL** in the **Administration** section of Sigma. Go to **Administration** > **Developer Access** > **API base URL**.

You can also determine your base URL to use for API requests by locating your cloud provider, then referring to the following table: in the table below, or from the

1. Locate your cloud provider in the **Administration** section of Sigma. Go to **Account > General Settings** and review the **Site** section for the **Cloud**.
2. After you know your hosting provider, determine the **Base URL** to use when authenticating to the API by referring to the following table.

| Provider      | Base URL                                  | Token URL      |
| :------------ | :---------------------------------------- | :------------- |
| AWS-US (West) | `https://aws-api.sigmacomputing.com`      | /v2/auth/token |
| AWS-US (East) | `https://api.us-a.aws.sigmacomputing.com` | /v2/auth/token |
| AWS-CA        | `https://api.ca.aws.sigmacomputing.com`   | /v2/auth/token |
| AWS-EU        | `https://api.eu.aws.sigmacomputing.com`   | /v2/auth/token |
| AWS-UK        | `https://api.uk.aws.sigmacomputing.com`   | /v2/auth/token |
| AWS-AU        | `https://api.au.aws.sigmacomputing.com`   | /v2/auth/token |
| Azure-US      | `https://api.us.azure.sigmacomputing.com` | /v2/auth/token |
| Azure-EU      | `https://api.eu.azure.sigmacomputing.com` | /v2/auth/token |
| Azure-CA      | `https://api.ca.azure.sigmacomputing.com` | /v2/auth/token |
| Azure-UK      | `https://api.uk.azure.sigmacomputing.com` | /v2/auth/token |
| Azure-AU      | `https://api.au.azure.sigmacomputing.com` | /v2/auth/token |
| GCP           | `https://api.sigmacomputing.com`          | /v2/auth/token |

## Make API calls

After you complete the prerequisites, you can start making API calls. You can use any of the following:

* cURL from the command line.
* Postman or another API client.
* Write a script using your preferred language.
* The web interface of the REST API documentation to make test API calls.

The reference pages for each API endpoint include code samples for a wide variety of languages, such as Node.js, Ruby, Python, and more.

To download the API definition for use with Postman or another API client, click the following button:

Download OpenAPI spec

You can follow the <a href="https://quickstarts.sigmacomputing.com/guide/sigma_api_with_postman/index.html" target="_blank">Sigma API with Postman</a> QuickStart for more guidance.

### Example scripts and recipes

For code examples and scripts for common use cases, you can refer to the following:

* [API recipes](https://help.sigmacomputing.com/recipes) for code samples that use the Sigma REST API.
* <a href="https://github.com/sigmacomputing/sigma-sample-api" target="_blank">Sample API GitHub repository</a> for the code files that use the Sigma REST API.
* <a href="https://quickstarts.sigmacomputing.com/guide/developers_quickstarts_api_tookit/index.html" target="_blank">QuickStarts API toolkit</a> for an interactive, prototype-friendly interface for running the example code samples.

You can use these scripts and code samples as a starting point for programmatically interacting with the API and for help understanding common patterns and flows.

### API limits

The following rate limits apply:

* The `v2/auth/token` endpoint is rate limited to 1 request per second.
* The `v2/workbooks/{workbookId}/export` and `/reports/{reportId}/export` endpoints are rate limited to 400 requests per minute.
* The `v2/workbooks/{workbookId}/send` and `/v2/reports/{reportId}/send` endpoints are rate limited to 100 requests per minute.
* The `/v2/query/{queryId}/download` endpoint is rate limited to 400 requests per minute.

Paginated responses from API endpoints that support pagination are also limited in size:

* Default page size: 50
* Max page size: 1000

### API errors

If you receive a 401 unauthorized error response from the API, your API token might be expired:

```json json
{
    "requestId": "2da86966-9666-48e6-b100-ea47a8d9fdbe",
    "message": "We cannot verify your identity. Please try again later.",
    "code": "unauthorized"
}
```

Your API token expires after 1 hour. To refresh your token or get a new one, see [Get access token](/reference/post-token).

Admins can also restrict access to the API according to the IP address used to make the API request. See [Restrict API access by IP address](/docs/restrict-access-to-sigma-by-ip-address).