DX Web API
The DX Web API is an interface for querying information from and enacting change in a DX workspace. Use it for interfacing with data about snapshots, teams, scorecards, users, and more.
Basic overview
The DX Web API is a collection of HTTP RPC-style methods, all with URLs in the form https://api.getdx.com/METHOD_FAMILY.method. While it’s not a REST API, those familiar with REST should be at home with its foundations in HTTP.
When sending a HTTP POST, you may provide your arguments as either standard POST parameters, or you may use JSON instead. Use HTTPS, SSL, and TLS v1.2 or above when calling all methods.
Authentication
Authenticate your Web API requests by providing a bearer token in the Authorization HTTP header of your outbound requests. You can generate API tokens in the DX admin area.
Rate limits
The DX Web API relies on rate limits to help provide a predictably pleasant experience for users.
Requests are limited to 1000 requests per minute. Rate limits are applied per account and are calculated using a sliding window.
When you exceed the rate limit, you’ll receive a 429 Too Many Requests HTTP status code. You should implement exponential backoff and retry logic in your applications to handle rate limiting gracefully.
Scopes
When creating an API key, you select scopes that control what the key can access. Each scope grants permission to a specific set of API methods. Follow the principle of least privilege by only enabling the scopes your integration needs.
snapshots:read is required for all API keys and is enabled by default.
| Scope | Description | Methods |
|---|---|---|
snapshots:read |
Read snapshot data, teams, users, org files, and most read-only endpoints. Required for all keys. | snapshots.list, snapshots.info, teams.list, teams.info, orgfiles.upload, orgfiles.teamHierarchy.get, queries.datafeed and others |
snapshots:admin |
Full snapshot administration, including exporting snapshot files. | snapshots.getFile |
catalog:read |
Read catalog entities, entity types, properties, relation definitions, and relation edges. | catalog.entities.list, catalog.entities.info, catalog.entityTypes.list, catalog.relationEdges.list, catalog.relations.list, catalog.relations.info, and others |
catalog:write:entities |
Create, update, and delete catalog entities, entity types, relations, and relation edges. | catalog.entities.create, catalog.entities.update, catalog.entities.upsert, catalog.entities.delete, catalog.entityTypes.create, catalog.entityTypes.update, catalog.relations.create, catalog.relationEdges.add, and others |
scorecards:read |
Read scorecards and initiatives. | scorecards.list, scorecards.info, initiatives.list, initiatives.info |
scorecards:write |
Create, update, and delete scorecards. | scorecards.create, scorecards.update, scorecards.delete |
teams:manage |
Upload and manage org hierarchy files. | orgfiles.upload |
user_groups:read |
Read user groups. | userGroups.list, userGroups.get |
user_groups:write |
Create, update, and delete user groups. | userGroups.create, userGroups.update, userGroups.delete |
users:write |
Update user profiles and custom attributes. | users.update, users.attributes.update |
workflows:read |
Read workflow run details. | workflowRuns.info |
workflowRuns:writeEvents |
Post messages, add links, and change status on workflow runs. | workflowRuns.postMessage, workflowRuns.addLink, workflowRuns.changeStatus |
workflowRuns:trigger |
Trigger workflow runs. | workflowRuns.trigger |
datacloud:query |
Run ad hoc Data Studio SQL queries and retrieve query-run status and results. | studio.queryRuns.execute, studio.queryRuns.info, studio.queryRuns.results |
platformx:manage |
Create and manage PlatformX projects. | platformx.projects.create, platformx.projects.list |
Making requests
Requests can be sent as JSON or as URL-encoded form data. Ensure to set header Content-Type: application/json when sending JSON
Here’s a quick example of a request:
curl -X GET https://api.getdx.com/snapshots.list \
--header 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx'Evaluating responses
Responses from the API are in JSON format. Successful requests return an ok: true status, while errors provide ok: false with an error code and message.
HTTP Status Codes
- 200 - Request succeeded.
- 202 - Request was accepted for asynchronous processing.
- 303 - Follow the redirect to download a file.
- 409 - The request is valid, but the query run is not complete yet.
- 410 - The requested query run results have expired.
- 422 - There was an error with your request.
- 429 - You exceeded a rate limit.
Success Response Body
The response will always contain an ok property which is true when it is successful. This is in addition to the 200 OK status.
{
"ok": true
}Error Response Body
When there is an error, the ok property will be false and details about the error will be included.
{
"ok": false,
"error": "invalid_arguments"
}