Data Studio's REST API provides a RESTful interface which can be integrated programmatically, allowing you to fully automate or speed up certain operations, such as:

  • Updating external system credentials.
  • Listing all objects in an Environment or Space.
  • Creating and managing Datasets, Spaces, Users, User Groups, Roles, and Permissions.
  • Sharing objects and include them into Spaces.
  • Executing Workflows and Schedules.
  • Importing, synching, and exporting metadata.
  • Generating audit information.
  • Generating system monitoring metrics.
  • Querying Dataset creation/refresh status.
  • Retrieving API key information.
  • Uploading files for use by other APIs.

Getting started

Authentication

All API requests require an API key for authentication. Follow the steps below to generate an API key:

  1. Click the user icon in the top right corner and select Manage API keys.
  2. Click Create new API Key.
  3. Enter a name for the key and specify the number of days until it expires. The ‘Maximum days for API Keys’ can be adjusted by editing the Environment settings.
  4. Select the API permission(s) you want to associate with the key.
  5. Click Generate.
  6. Click Copy to take a copy of the generated key. You will have to paste it in the authorization header of your request.

Your authorization header should look like this:

{
    "Authorization": "<Environment external label> <Your API Key>"
}

API reference

The full interactive API reference is available in Swagger UI, allowing you to test resources and get a better understanding of all requests and parameters.

You can access it by clicking the help icon (?) in the top right corner of Data Studio followed by 'Try out the API', which will open the page: http://<server>/api/docs/index.html. If you've installed Data Studio locally using the default server port, the URL will be http://localhost:7701/api/docs/index.html.

Please refer below for the full listing of APIs together with the user capabilities and API permission requirements:

Audit operations

Action Request method & endpoint Required user capabilities Required API permission
List event information GET /{tenancyId}/events Installation Manager Audit operations (Read)
List session information GET /{tenancyId}/sessions Installation Manager Audit operations (Read)

Metric operations

Action Request method & endpoint Required user capabilities Required API permission
Returns the most used performance metrics GET /metrics View System Information Metrics operations (Read)
Lists all recorded metric GET /metrics/list View System Information Metrics operations (Read)
Returns detailed information for the specified metric GET /metrics/{name} View System Information Metrics operations (Read)

REST API Key operations

Action Request method & endpoint Required user capabilities Required API permission
Retrieve API key information GET /{tenancyId}/apiKey API access Rest API key operations (Read keys)

Role operations

Action Request method & endpoint Required user capabilities Required API permission
List all Roles GET /{tenancyId}/roles Access Designer Interface Security operations (Read)
Retrieve a Role GET /{tenancyId}/roles/{roleId} Access Designer Interface Security operations (Read)
Create a Role POST /{tenancyId}/roles Manage Roles and Permissions Security operations (Update)
Patch a Role PATCH /{tenancyId}/roles/{roleId} Manage Roles and Permissions Security operations (Update)
Update a Role PUT /{tenancyId}/roles Manage Roles and Permissions Security operations (Update)
Delete a Role DELETE /{tenancyId}/roles/{roleId} Manage Roles and Permissions Security operations (Update)

User operations

Action Request method & endpoint Required user capabilities Required API permission
List all Users GET /{tenancyId}/users Access Designer Interface Security operations (Read)
Retrieve a User GET /{tenancyId}/users/{userId} Access Designer Interface Security operations (Read)
Create a User POST /{tenancyId}/users Manage Users Security operations (Update)
Patch a User PATCH /{tenancyId}/users/{userId} Manage Users Security operations (Update)
Update a User PUT /{tenancyId}/users/{userId} Manage Users Security operations (Update)
Delete a User DELETE /{tenancyId}/users/{userId} Manage Users Security operations (Update)

User group operations

Action Request method & endpoint Required user capabilities Required API permission
List all Users Groups GET /{tenancyId}/usergroups Access Designer Interface Security operations (Read)
Retrieve a User Group GET /{tenancyId}/usergroups/{userGroupId} Access Designer Interface Security operations (Read)
Create a User Group POST /{tenancyId}/usergroups Manage User Groups Security operations (Update)
Patch a User Group PATCH /{tenancyId}/usergroups/{userGroupId} Manage User Groups Security operations (Update)
Update a User Group PUT /{tenancyId}/usergroups/{userGroupId} Manage User Groups Security operations (Update)
Delete a User Group DELETE /{tenancyId}/usergroups/{userGroupId} Manage User Groups Security operations (Update)

External systems and credential operations

Action Request method & endpoint Required user capabilities Required API permission
List all External Systems GET /{tenancyId}/externalsystems View External Systems External system and credential operations (Read)
List all credentials for an External System GET /{tenancyId}/externalsystems/{externalSystemId}/credentials View External Systems External system and credential operations (Read)
Retrieve the credential fields for an External System GET /{tenancyId}/externalsystems/{externalSystemId}/credentials/fields View External systems External system and credential operations (Read)
Create a Credential POST /{tenancyId}/externalsystems/{externalSystemId}/credentials Manage Connections to External Systems External system and credential operations (Update)
Test the connection for an External System GET /{tenancyId}/externalsystems/{externalSystemId}/credentials/{credentialId}/testconnection View External systems External system and credential operations (Read)
Patch a Credential PATCH /{tenancyId}/externalsystems/{externalSystemId}/credentials/{credentialId} Manage Connections to External Systems External system and credential operations (Update)
Delete a Credential DELETE /{tenancyId}/externalsystems/{externalSystemId}/credentials/{credentialId} Manage Connections to External Systems External system and credential operations (Delete)

Metadata operations

Action Request method & endpoint Required user capabilities Required API permission
List exportable objects in a Space GET /{tenancyId}/exportableobjects/{spaceId} Export Metadata Metadata exchange operations (Export)
Export metadata POST /{tenancyId}/export/{spaceId} Export Metadata Metadata exchange operations (Export)
Import metadata POST /{tenancyId}/import/{spaceId} Import Metadata Metadata exchange operations (Import)
Synchronize metadata POST /{tenancyId}/synchronize/{spaceId} Synchronize Metadata Between Environments Metadata exchange operations (Synchronize)
Upload a file (dmx for import/sync metadata or other files to create datasets) POST /{tenancyId}/upload Import Metadata or Create and Edit Datasets Metadata exchange operations (Synchronize)

Solutions operations

Action Request method & endpoint Required user capabilities Required API permission
Deploy solution POST /{tenancyId}/deploy Synchronize Metadata Between Environments Metadata exchange operations (Synchronize)

Chart operations

Action Request method & endpoint Required user capabilities Required API permission
Retrieve sharing details for a Chart GET /{tenancyId}/charts/{spaceId}/{chartId}/sharing Create and Edit Charts Chart operations (Share)
Update Chart sharing settings PUT /{tenancyId}/charts/{spaceId}/{chartId}/sharing Create and Edit Charts Chart operations (Share)
Include or unincluded Chart in a Space PUT /{tenancyId}/charts/{spaceId}/include Create and Edit Charts Chart operations (Share)

Dataset operations

Action Request method & endpoint Required user capabilities Required API permission
List all Datasets GET /{tenancyId}/datasets View Datasets Dataset operations (Read Dataset metadata)
List all Datasets in a Space GET /{tenancyId}/datasets/{spaceID} View Datasets Dataset operations (Read Dataset metadata)
Retrieve a Dataset GET /{tenancyId}/datasets/{spaceId}/{datasetId} View Datasets Dataset operations (Read Dataset metadata)
Delete a Dataset DELETE /{tenancyId}/datasets/{spaceId}/{datasetId} Create and Edit Datasets Dataset operations (Delete)
Update Dataset settings PATCH /{tenancyId}/datasets/{spaceId}/{datasetId} Create and Edit Datasets Dataset operations (Update)
Create a Dataset POST /{tenancyId}/datasets/create Create and Edit Datasets Dataset operations (Create)
Refresh a Dataset PUT /{tenancyId}/datasets/refresh View External systems capability Dataset operations (Refresh)
Query the status of a Dataset GET /{tenancyId}/datasets/status/{statusId} Create and Edit Datasets or View External Systems Dataset operations (Read Dataset status)

Function Operations

Action Request method & endpoint Required user capabilities Required API permission
List Functions available to all Spaces GET /{tenancyId}/functions View Functions Function operations (Read Functions)
List Functions available to a Space GET /{tenancyId}/functions/{spaceId} View Functions Function operations (Read Functions)
Create a Function POST /{tenancyId}/functions/{spaceId} Create and Edit Functions Function operations (Update Functions)
Retrieve a Function GET /{tenancyId}/functions/{spaceId}/{functionId} View Functions Function operations (Read Functions)
Update a Function PUT /{tenancyId}/functions/{spaceId}/{functionId} Create and Edit Functions Function operations (Update Functions)
Delete a Function DELETE /{tenancyId}/functions/{spaceId}/{functionId} Create and Edit Functions Function operations (Delete Functions)
Publish a Function POST /{tenancyId}/functions/{spaceId}/{functionId}/publish Create and Edit Functions Function operations (Update Functions)
Retrieve the sharing details for a Function GET /{tenancyId}/functions/{spaceId}/{functionId}/sharing Create and Edit Functions Function operations (Share)
Update the sharing settings for a Function PUT /{tenancyId}/functions/{spaceId}/{functionId}/sharing Create and Edit Functions Function operations (Share)

Ruleset Operations

Action Request method & endpoint Required user capabilities Required API permission
List Rulesets available to all Spaces GET /{tenancyId}/rulesets View Rulesets Ruleset operations (Read Ruleset)
List Rulesets available to a Space GET /{tenancyId}/rulesets/{spaceId} View Rulesets Ruleset operations (Read Ruleset)
Create a Ruleset POST /{tenancyId}/rulesets/{spaceId} Create and Edit Rulesets Ruleset operations (Update Ruleset)
Retrieve a Ruleset GET /{tenancyId}/rulesets/{spaceId}/{rulesetId} View Rulesets Ruleset operations (Read Ruleset)
Update a Ruleset PUT /{tenancyId}/rulesets/{spaceId}/{rulesetId} Create and Edit Rulesets Ruleset operations (Update Ruleset)
Delete a Ruleset DELETE /{tenancyId}/rulesets/{spaceId}/{rulesetId} Create and Edit Rulesets Ruleset operations (Delete Ruleset)
Publish a Ruleset POST /{tenancyId}/rulesets/{spaceId}/{rulesetId}/publish Create and Edit Rulesets Ruleset operations (Update Ruleset)
Retrieve the sharing details for a Ruleset GET /{tenancyId}/rulesets/{spaceId}/{rulesetId}/sharing Create and Edit Rulesets Ruleset operations (Share Ruleset)
Update the sharing settings for a Ruleset PUT /{tenancyId}/rulesets/{spaceId}/{rulesetId}/sharing Create and Edit Rulesets Ruleset operations (Share Ruleset)
Include or unincluded a Ruleset in a Space PUT /{tenancyId}/rulesets/{spaceId}/include Create and Edit Rulesets Ruleset operations (Share Ruleset)

Space Operations

Action Request method & endpoint Required user capabilities Required API permission
List all Spaces GET /{tenancyId}/spaces Access Designer Interface Space operations (Read)
Retrieve a Space GET /{tenancyId}/spaces/{spaceId} Access Designer Interface Space operations (Read)
Create a Space POST /{tenancyId}/spaces Create and Edit Spaces Space operations (Update)
Update a Space PUT /{tenancyId}/spaces/{spaceId} Create and Edit Spaces Space operations (Update)
Delete a Space DELETE /{tenancyId}/spaces/{spaceId} Create and Edit Spaces Space operations (Delete)
Patch a Space PATCH /{tenancyId}/spaces/{spaceId} Create and Edit Spaces Space operations (Update)

View Operations

Action Request method & endpoint Required user capabilities Required API permission
List all Views GET /{tenancyId}/views Access Designer Interface View operations (Read)
List Views in a Space GET /{tenancyId}/views/{spaceId} Access Designer Interface View operations (Read)
Retrieve the sharing details for a View GET /{tenancyId}/views/{spaceId}/{viewId}/sharing Create and Edit Views View operations (Share)
Update View sharing settings PUT /{tenancyId}/views/{spaceId}/{viewId}/sharing Create and Edit Views View operations (Share)
Include or unincluded View in a Space PUT /{tenancyId}/views/{spaceId}/include Create and Edit Views View operations (Share)

Workflow Operations

Action Request method & endpoint Required user capabilities Required API permission
List all Workflows GET /{tenancyId}/workflows View Workflows Workflow operations (Read)
List Workflows available to a Space GET /{tenancyId}/workflows/{spaceId} View Workflows Workflow operations (Read)
Retrieve workflow settings GET /{tenancyId}/workflows/{spaceId}/{workflowId}/settings/{versionType} View Workflows Workflow operations (Read)
Retrieve the sharing settings for a Workflow GET /{tenancyId}/workflows/{spaceId}/{workflowId}/sharing Create and Edit Workflows Workflow operations (Share)
Update Workflow sharing settings PUT /{tenancyId}/workflows/{spaceId}/{workflowId}/sharing Create and Edit Workflows Workflow operations (Share)
Include or unincluded Workflow in a Space PUT /{tenancyId}/workflows/{spaceId}/include Create and Edit Workflows Workflow operations (Share)

Schedule operations

Action Request method & endpoint Required user capabilities Required API permission
Retrieve the status for a Schedule GET /{tenancyId}/schedule/status/{executionId} Monitor Workflow Workflow operations (Read Jobs)
Execute a Schedule POST /{tenancyId}/schedule/runnow Execute Workflows Workflow operations (Submit Jobs)

Worfklow execution operations

Action Request method & endpoint Required user capabilities Required API permission
List all Jobs GET /{tenancyId}/jobs Monitor Workflow Workflow operations (Read Jobs)
Retrieve details for a Job GET /{tenancyId}/jobs/{executionId} Monitor Workflow Workflow operations (Read Jobs)
Execute a workflow POST /{tenancyId}/jobs View Workflows & Execute Workflows Workflow operations (Submit Jobs)

Troubleshooting

If you get a HTTP response with a 401 error, the possible causes are:

Possible cause Error message in HTTP response body
Missing user capabilities The API key must have the following capabilities: {required capabilities}
User (creator of API key) is disabled Unauthorized
Invalid API key Unauthorized
Expired API key Unauthorized
Missing API key Unauthorized
Missing API key permissions Unauthorized
Incorrect environment label Unauthorized
Missing environment label Unauthorized