--- title: "DX Web API" canonical_url: "https://docs.getdx.com/webapi/overview/" md_url: "https://docs.getdx.com/webapi/overview.md" last_updated: "2026-06-08" --- # 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. For machine-to-machine traffic, generate an organization token from [**Admin** -> **Organization tokens**](https://app.getdx.com/admin/organizationtokens). For user-scoped access, use a [personal access token](https://docs.getdx.com/personal-access-tokens/). ## 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 organization token or personal access token, you select scopes that control what the token 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. For organization tokens, `snapshots:read` is required and enabled by default. | Scope | Description | Methods | | -------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `snapshots:read` | Read snapshot data, teams, users, org files, and most read-only endpoints. Required for organization tokens. | [snapshots.list](https://docs.getdx.com/webapi/methods/snapshots.list/), [snapshots.info](https://docs.getdx.com/webapi/methods/snapshots.info/), [teams.list](https://docs.getdx.com/webapi/methods/teams.list/), [teams.info](https://docs.getdx.com/webapi/methods/teams.info/), [orgfiles.upload](https://docs.getdx.com/webapi/methods/orgfiles.upload/), [orgfiles.teamHierarchy.get](https://docs.getdx.com/webapi/methods/orgfiles.teamhierarchy.get/), [queries.datafeed](https://docs.getdx.com/webapi/methods/queries.datafeed/) and others | | `snapshots:admin` | Full snapshot administration, including exporting snapshot files. | [snapshots.getFile](https://docs.getdx.com/webapi/methods/snapshots.getfile/) | | `catalog:read` | Read catalog entities, entity types, properties, relation definitions, and relation edges. | [catalog.entities.list](https://docs.getdx.com/webapi/methods/catalog.entities.list/), [catalog.entities.info](https://docs.getdx.com/webapi/methods/catalog.entities.info/), [catalog.entityTypes.list](https://docs.getdx.com/webapi/methods/catalog.entitytypes.list/), [catalog.relationEdges.list](https://docs.getdx.com/webapi/methods/catalog.relationedges.list/), [catalog.relations.list](https://docs.getdx.com/webapi/methods/catalog.relations.list/), [catalog.relations.info](https://docs.getdx.com/webapi/methods/catalog.relations.info/), and others | | `catalog:write:entities` | Create, update, and delete catalog entities, entity types, relations, and relation edges. | [catalog.entities.create](https://docs.getdx.com/webapi/methods/catalog.entities.create/), [catalog.entities.update](https://docs.getdx.com/webapi/methods/catalog.entities.update/), [catalog.entities.upsert](https://docs.getdx.com/webapi/methods/catalog.entities.upsert/), [catalog.entities.delete](https://docs.getdx.com/webapi/methods/catalog.entities.delete/), [catalog.entityTypes.create](https://docs.getdx.com/webapi/methods/catalog.entitytypes.create/), [catalog.entityTypes.update](https://docs.getdx.com/webapi/methods/catalog.entitytypes.update/), [catalog.relations.create](https://docs.getdx.com/webapi/methods/catalog.relations.create/), [catalog.relationEdges.add](https://docs.getdx.com/webapi/methods/catalog.relationedges.add/), and others | | `scorecards:read` | Read scorecards and initiatives. | [scorecards.list](https://docs.getdx.com/webapi/methods/scorecards.list/), [scorecards.info](https://docs.getdx.com/webapi/methods/scorecards.info/), [initiatives.list](https://docs.getdx.com/webapi/methods/initiatives.list/), [initiatives.info](https://docs.getdx.com/webapi/methods/initiatives.info/) | | `scorecards:write` | Create, update, and delete scorecards. | [scorecards.create](https://docs.getdx.com/webapi/methods/scorecards.create/), [scorecards.update](https://docs.getdx.com/webapi/methods/scorecards.update/), [scorecards.delete](https://docs.getdx.com/webapi/methods/scorecards.delete/) | | `teams:manage` | Upload and manage org hierarchy files. | [orgfiles.upload](https://docs.getdx.com/webapi/methods/orgfiles.upload/) | | `userGroups:read` | Read user groups. | [userGroups.list](https://docs.getdx.com/webapi/methods/user-groups.list/), [userGroups.get](https://docs.getdx.com/webapi/methods/user-groups.get/) | | `userGroups:write` | Create, update, and delete user groups. | [userGroups.create](https://docs.getdx.com/webapi/methods/user-groups.create/), [userGroups.update](https://docs.getdx.com/webapi/methods/user-groups.update/), [userGroups.delete](https://docs.getdx.com/webapi/methods/user-groups.delete/) | | `users:write` | Update user profiles and custom attributes. | [users.update](https://docs.getdx.com/webapi/methods/users.update/), [users.attributes.update](https://docs.getdx.com/webapi/methods/users.attributes.update/) | | `workflows:read` | Read workflow definitions and workflow run details. | [workflows.list](https://docs.getdx.com/webapi/methods/workflows.list/), [workflowRuns.info](https://docs.getdx.com/webapi/methods/workflowruns.info/) | | `workflowRuns:writeEvents` | Post messages, add links, and change status on workflow runs. | [workflowRuns.postMessage](https://docs.getdx.com/webapi/methods/workflowruns.postmessage/), [workflowRuns.addLink](https://docs.getdx.com/webapi/methods/workflowruns.addlink/), [workflowRuns.changeStatus](https://docs.getdx.com/webapi/methods/workflowruns.changestatus/) | | `workflowRuns:trigger` | Trigger workflow runs. | [workflowRuns.trigger](https://docs.getdx.com/webapi/methods/workflowruns.trigger/) | | `datacloud:query` | Run ad hoc Data Studio SQL queries and retrieve query-run status and results. | [studio.queryRuns.execute](https://docs.getdx.com/webapi/methods/studio.queryruns.execute/), [studio.queryRuns.info](https://docs.getdx.com/webapi/methods/studio.queryruns.info/), [studio.queryRuns.results](https://docs.getdx.com/webapi/methods/studio.queryruns.results/) | | `platformx:manage` | Create and manage PlatformX projects. | [platformx.projects.create](https://docs.getdx.com/webapi/methods/platformx.projects.create/), [platformx.projects.list](https://docs.getdx.com/webapi/methods/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: ```bash 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" } ``` --- ## Sitemap [Overview of all docs pages](/llms.txt)