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

About the API

The Sigma API is built around REST principles, leveraging the OpenAPI specification. 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 endpoint for files requested with the Export data from a 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 for your API calls.
• Generate API client ID and secret. You can also have an organization admin generate credentials for you.
• Use your credentials to generate a bearer token.

Identify your API request URL

The URL you use to send API requests depends on the cloud your Sigma organization is hosted on.

You can locate your cloud provider in the Administration section of Sigma. Go to Account > General Settings and review the Site section for the Cloud.

After you know your hosting provider, determine the Base URL to use when authenticating to the API by referring to the following table:

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:

You can follow the Sigma API with Postman 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
• Sample API GitHub repository

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 v2/auth/token endpoint is rate limited to 1 request per second.

The Sigma API does not enforce a limit on the number of API requests you can send per day.

There is a limit of paginated responses from API endpoints that support pagination:

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

{
    "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.

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 (Beta).