Connection API
The Connection API endpoints allow you to create, update, list, delete and test a data warehouse connection.
Summary of Content
Endpoints
The Connection Object
Attributes
Create a Connection
List Connections
Look Up a Connection
Update a Connection
Test a Connection
Delete a Connection
Related Resources
Endpoints
Try these endpoints in Swagger
POST /v2/connections
Use this endpoint to create a data warehouse connection object. Learn more.
GET /v2/connections?limit=<number>&page=<page-string>
Returns a list of the active data warehouse connection objects.
GET /v2/connections/{connectionId}
Returns a connection object based on the input connectionId. Learn more.
PUT /v2/connections/:id
This endpoint allows you to update or restore a connection object to a data warehouse. Learn more.
GET /v2/connections/:connectionId/test
Use this endpoint to validate a data warehouse connection object. Learn more.
DELETE /v2/connections/:connectionId
Use this endpoint to delete a data warehouse connection object. Learn more.
The Connection Object
Attributes
organizationId string
The unique identifier associated with the connections' organization.
connectionId string
The unique identifier associated with the individual connection.
isSample boolean
True if the connection contains Sigma sample data.
lastActiveAt string
The timestamp at which a query was last run against the connection.
name string
The connection's name, as is listed in Sigma.
type string
The connection's Cloud Data Warehouse (CDW) provider.
useOauth boolean | undefined
True if access to the connection is authenticated with OAuth through your Identity Provider (IdP).
Note: Only applicable to Snowflake connections.
createdBy string
The unique identifier, memberId, of the organization member who created the connection.
updatedBy string
The unique identifier, memberId, of the organization member who last updated the connection.
createdAt string
The timestamp at which the connection was created.
updatedAt string
The timestamp at which the connection was last updated.
isArchived boolean | undefined
True if the connection is archived.
{
"organizationId": "cf2de26e-9a2c-4c58-ba1c-91a0955df7ez",
"connectionId": "48726c98-8495-4488-bb6e-108a115b732df",
"isSample": false,
"lastActiveAt": "2022-02-28T21:26:52.033Z",
"name": "My First Connection",
"type": "snowflake",
"useOauth": false,
"createdBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
"createdAt": "2021-10-04T20:36:41.044Z",
"updatedAt": "2021-10-08T21:38:25.044Z"
isArchived: false
}
Create a Connection
Use this endpoint to create a data warehouse connection.
POST /v2/connections
Permissions
- You must be an admin to use this endpoint.
Parameters
Note: The parameters below map to the fields in the data warehouse connection section in the administration portal. Each data warehouse uses a different schema, see swagger examples for more information.
details | { <db details object> } | [required]
The key/value pairs for this parameter are determined by the specific data warehouse connection. The example below reflects a Snowflake connection.
{
"details": {
"type": "snowflake",
"account": "tester",
"host": "testing.snowtest.com",
"password": "<password>",
"role": "A_ROLE",
"user": "THE_DEV",
"warehouse": "TEST_WAREHOUSE",
"writeAccess": {
"writeDatabase": "PUBLIC_API",
"writeSchema": "PUBLIC",
"materializationWarehouse": ""
}
}
name | string | [required]
The name of the connection.
description | { <description object> } | [optional]
Any key/value pair.
timeoutSecs | number | [optional]
Number of seconds Sigma waits for a query to return results before it times out.
useFriendlyNames | boolean | [true or false]
If set to "true", Sigma will make the column names more readable. A column with a name like "SALES_JSON" would become "Sales Json". If set to "false," then the warehouse column names are used, unaltered.
cURL Request
The example below is based on a Snowflake connection.
curl -X 'POST' \
'https://api.sigmacomputing.com/v2/connections/' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"details": {
"account": "snowflake",
"user": "string",
"host": "string",
"password": "string",
"role": "string",
"user": "string",
"warehouse": "string",
"writeAccess": {
"writeDatabase": "string",
"writeSchema": "string",
"materializationWarehouse": "string"
}
},
"name": "string",
"timeoutSecs": "integer",
"useFriendlyNames": boolean
}
Response
{
"organizationId": "string",
"connectionId": "string",
"isSample": boolean,
"lastActiveAt": "2022-07-21T23:05:00.453Z",
"name": "string",
"type": "string",
"useOauth": boolean,
"createdBy": "string",
"updatedBy": "string",
"createdAt": "string",
"updatedAt": "string",
"isArchived": boolean
}
Example
Example Request:
curl -X 'POST' \
'https://api.sigmacomputing.com/v2/connections/' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"details": {
"type": "snowflake",
"account": "tester",
"host": "testing.snowtest.com",
"password": "<password>",
"role": "A_ROLE",
"user": "THE_DEV",
"warehouse": "TEST_WAREHOUSE",
"writeAccess": {
"writeDatabase": "PUBLIC_API",
"writeSchema": "PUBLIC",
"materializationWarehouse": ""
}
}
"name": "string",
"timeoutSecs": "integer",
"useFriendlyNames": boolean,
}
Example Response:
{
"organizationId": "98da0f2b-8482-4f37-833a-0b042443f1c9",
"connectionId": "c96b6e71-a40f-47a3-a84d-33a742eead7f",
"isSample": false,
"lastActiveAt": "2022-06-22T20:47:07.000Z",
"name": "test_write_7_ctas",
"type": "snowflake",
"useOauth": false,
"createdBy": "f0hGBLjzzmMNW3fWKiCUUDKYDlKNz",
"updatedBy": "f0hGBLjzzmMNW3fWKiCUUDKYDlKNz",
"createdAt": "2022-06-22T20:47:07.899Z",
"updatedAt": "2022-06-22T20:47:07.899Z",
"isArchived": false
}
List Connections
Use this endpoint to list the active data warehouse connections.
GET /v2/connections?limit=<number>&page=<page-string>
Permissions
- The user account associated with the API access token must have permission to access the requested connection.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Query Parameters
page | string [optional]
An identifier used for pagination.
limit | number [optional]
The number of connections to return.
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/connections?limit=<number>&page=<page-string> \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
{
"entries": [
{
"organizationId": 'string',
"connectionId": 'string',
"isSample": boolean,
"lastActiveAt": '2022-06-17T10:03:25.000Z',
"name": 'string',
"type": 'string',
"useOauth": boolean,
"createdBy": 'string',
"updatedBy": 'string',
"createdAt": '2022-06-17T10:03:25.311Z',
"updatedAt": '2022-06-17T10:03:25.311Z',
"isArchived": boolean
},
{
"organizationId: 'string',
"connectionId: 'string',
"isSample: boolean,
"lastActiveAt: '2022-06-17T10:03:25.000Z',
"name: 'string',
"type: 'string',
"useOauth: boolean,
"createdBy: 'string',
"updatedBy: 'string',
"createdAt: '2022-06-17T10:03:25.306Z',
"updatedAt: '2022-06-17T10:03:25.306Z',
"isArchived: boolean
},
],
"hasMore": boolean,
"nextPage": 'string'
"total": 2
Example
Example Request:
curl --location --request GET 'https://api.sigmacomputing.com/v2/connections?limit=<number>&page=<page-string> \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
{
entries: [
{
"organizationId": 'a7f0d337-99d4-4c26-be65-1d657343c45e',
"connectionId": 'd378f08a-4fe9-456e-bca6-43ec6b540f55',
"isSample": false,
"lastActiveAt": '2022-06-17T10:03:25.000Z',
"name": 'a_conn0002',
"type": 'snowflake',
"useOauth": false,
"createdBy"": '01faRqtvlAsPshvyd2D7qlcgcZJJv',
"updatedBy": '01faRqtvlAsPshvyd2D7qlcgcZJJv',
"createdAt": '2022-06-17T10:03:25.311Z',
"updatedAt": '2022-06-17T10:03:25.311Z',
"isArchived": false
},
{
"organizationId": 'a7f0d337-99d4-4c26-be65-1d657343c45e',
"connectionId": 'f046df8b-a528-42a3-a1d7-c11f4740e067',
"isSample": false,
"lastActiveAt": '2022-06-17T10:03:25.000Z',
"name": 'b_conn0001',
"type": 'snowflake',
"useOauth": false,
"createdBy": '01faRqtvlAsPshvyd2D7qlcgcZJJv',
"updatedBy": '01faRqtvlAsPshvyd2D7qlcgcZJJv',
"createdAt": '2022-06-17T10:03:25.306Z',
"updatedAt": '2022-06-17T10:03:25.306Z',
"isArchived": false
},
],
"hasMore": true,
"nextPage": '{"name":"c_conn0005","lastCreatedAt":1655460205324}'
Look Up a Connection
Returns a connection object based on the input connectionId.
GET /v2/connections/{connectionId}
Permissions
- The user account associated with the API access token must have permission to access the requested connection.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Parameters
None
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/connections/{connectionId}' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
{
"organizationId": string,
"connectionId": string,
"isSample": boolean,
"lastActiveAt": string,
"name": string,
"type": string,
"useOauth": boolean,
"createdBy": string,
"updatedBy": string,
"createdAt": string,
"updatedAt": string,
"isArchived": boolean
}
Example
Example Request:
curl --location --request GET 'https://api.sigmacomputing.com/v2/connections/48726c98-8495-4488-bb6e-108a115b732df' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
{
"organizationId": "cf2de26e-9a2c-4c58-ba1c-91a0955df7ez",
"connectionId": "65726g36-8495-4588-er6e-194a115b734kf",
"isSample": false,
"lastActiveAt": "2022-01-08T21:16:42.053Z",
"name": "My First Connection",
"type": "snowflake",
"useOauth": false,
"createdBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
"updatedBy": "6VZszXPJqLXpIezceRadESnwfPPUg",
"createdAt": "2021-08-09T20:33:41.044Z",
"updatedAt": "2021-10-08T21:28:25.044Z",
"isArchived": false
}
Update a Connection
Use this endpoint to update or restore a connection to a data warehouse.
PUT /v2/connections/:id
Note: We have deprecated the PATCH endpoint below. Use PUT instead.
PATCH /v2/connections/{connectionId}
Permissions
- You must be an admin to use this endpoint.
Parameters
Note: The parameters below map to the fields in the data warehouse connection section in the administration portal. Each data warehouse uses a different schema, see swagger examples for more information.
connectionId | string [required]
The ID of the connection to update or restore.
details | { <db details object> } | [required]
The key/value pairs for this parameter are determined by the specific data warehouse connection. The example below reflects a Snowflake connection.
{
"details": {
"type": "snowflake",
"account": "tester",
"host": "testing.snowtest.com",
"password": "<password>",
"role": "A_ROLE",
"user": "THE_DEV",
"warehouse": "TEST_WAREHOUSE",
"writeAccess": {
"writeDatabase": "PUBLIC_API",
"writeSchema": "PUBLIC",
"materializationWarehouse": ""
}
}
name | string | [required]
The name of the connection.
description | { <description object> } | [optional]
Any key/value pair.
timeoutSecs | number | [optional]
Number of seconds Sigma waits for a query to return results before timing out.
useFriendlyNames | boolean | [true or false]
If set to "true", Sigma will make the column names more readable. A column with a name like "SALES_JSON" would become "Sales Json". If set to "false," then the warehouse column names are used, unaltered.
restore | boolean [optional]
Set to true if the updated connection is archived and needs to be restored.
cURL Request
The example below is based on a Snowflake connection.
curl -X 'PUT' \
'https://api.sigmacomputing.com/v2/connections/:id' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"details": {
"account": "snowflake",
"user": "string",
"host": "string",
"password": "string",
"role": "string",
"user": "string",
"warehouse": "string",
"database": "string",
"writeAccess": {
"writeDatabase": "string",
"writeSchema": "string",
"materializationWarehouse": "string"
}
},
"name": "string",
"timeoutSecs": "integer",
"useFriendlyNames": "boolean"
}'Response
{
"organizationId": "string",
"connectionId": "string",
"isSample": boolean,
"lastActiveAt": "2022-07-21T23:05:00.453Z",
"name": "string",
"type": "string",
"useOauth": boolean,
"createdBy": "string",
"updatedBy": "string",
"createdAt": "string",
"updatedAt": "string",
"isArchived": boolean
}Example
Example Request:
curl -X 'PUT' \
'https://api.sigmacomputing.com/v2/connections/:id' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {access_token}' \
--data-raw '{
"details": {
"type": "snowflake",
"account": "tester",
"host": "testing.snowtest.com",
"password": "<password>",
"role": "A_ROLE",
"user": "THE_DEV",
"warehouse": "TEST_WAREHOUSE",
"writeAccess": {
"writeDatabase": "PUBLIC_API",
"writeSchema": "PUBLIC",
"materializationWarehouse": ""
}
},
"name": "string",
"timeoutSecs": "integer",
"useFriendlyNames": boolean,
"restore": true// Set to true if the updated connection is archived and needs to be restored}
Example Response:
{
"organizationId": "98da0f2b-8482-4f37-833a-0b042443f1c9",
"connectionId": "c96b6e71-a40f-47a3-a84d-33a742eead7f",
"isSample": false,
"lastActiveAt": "2022-06-22T20:47:07.000Z",
"name": "test_write_7_ctas",
"type": "snowflake",
"useOauth": false,
"createdBy": "f0hGBLjzzmMNW3fWKiCUUDKYDlKNz",
"updatedBy": "f0hGBLjzzmMNW3fWKiCUUDKYDlKNz",
"createdAt": "2022-06-22T20:47:07.899Z",
"updatedAt": "2022-06-22T20:47:07.899Z",
"isArchived": false
}
Test a Connection
Use this endpoint to validate a data warehouse connection.
GET /v2/connections/:connectionId/test
Permissions
- The user account associated with the API access token must have permission to updated the requested connection.
Note: If you encounter a permission error for the given endpoint, check with your organization Admin to verify your account type and permissions associated with your API token.
Path Parameters
connectionId | string [required]
The ID of the connection to delete.
cURL Request
curl --location --request GET 'https://api.sigmacomputing.com/v2/connections/:connectionId/test' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
{
"read": "SUCCESS",
"write": "SUCCESS"
}Example
Example Request:
curl --location --request GET'https://api.sigmacomputing.com/v2/connections/c96c6e71-a43f-47a3-a84d-33a742eead7f/test' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
200 OK
{
"read": "SUCCESS",
"write": "SUCCESS"
}
Delete a Connection
Use this endpoint to delete a data warehouse connection.
DELETE /v2/connections/:connectionId
Permissions
You must be an admin to use this endpoint.
Path Parameters
connectionId | string [required]
The ID of the connection to delete.
cURL Request
curl --location --request DELETE 'https://api.sigmacomputing.com/v2/connections/:connectionId' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Response
{}
Example
Example Request:
curl --location --request DELETE 'https://api.sigmacomputing.com/v2/connections/:1234' \
--header 'Authorization: Bearer {access_token}' \
--header 'Content-Type: application/json' \
Example Response:
{}
Related Resources
API Documentation
Get an API Token and Client ID
Identify Unique IDs in Sigma