Skip to main content

Get Started with Alteryx Analytics Cloud APIs

This page is a quick guide to using the Alteryx Analytics Cloud (AAC) Application Programming Interface (API). For detailed instructions and documentation, go to AAC to access the full API documentation based on your region...

Why Use APIs

You can accomplish many tasks programmatically using AAC APIs. This can be useful to execute a long series of commands that might otherwise be tedious to perform using the AAC User Interface (UI). Alternatively, you can automate and schedule tasks as needed using these APIs. These are a couple of examples of how you might use the AAC APIs:

  • Invite a batch of users to join AAC.

  • Revoke access for a batch of users.

  • Run a plan, flow, or job triggered by an event or events.

  • Create a batch of data connections.

API Overview

You can use a third-party client, such as curl, HTTPie, Postman, or the Insomnia rest client to test the AAC API.

Caution

When testing the API, you are working with your live production data. Changes you make have immediate effects on your production AAC environment.

For example, here is how to list all of your access tokens using curl:

curl -X GET 'https://us1.alteryxcloud.com/v4/apiAccessTokens' \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer <token>'

These are the key items to pay attention to in this request:

  • The header for Content-type has been set to application/json. AAC requires this for nearly all of its APIs.

  • Authentication is by Bearer token. Replace <token> with your own token. Note that you shouldn’t include <> with your token.

Caution

Ensure the security of your access tokens. Anyone with your token can use AAC APIs as though they are you.

After you replace the token value with your own, execute the above command. The result might look like this:

{
  "data": [
    {
      "tokenId": "<your tokenID>",
      "description": "The description of your token",
      "createdAt": "The date the token was created",
      "expiredAt": "The date the token will expire",
      "lastUsed": "Likely the current time",
      "person": {
        "name": "Your Name",
        "email": "Your email",
        "id": <your id>
      }
    }
  ]
}

A Simple Example Using APIs

Here is an example of how you might use the AAC APIs in day-to-day use. Say you want to invite a list of users to use AAC. Specifically, you want to invite them to a workspace.

First, you need to get the workspace ID that you are inviting users to:

curl -X GET 'https://us1.alteryxcloud.com/v4/workspaces' \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer <token>'

That should return JSON similar to:

[
  {
    "id": 123,
    "name": "workspace1",
    "state": "active",
    "lastStateChange": null,
    "deleted_at": null,
    "custom_url": "url",
    "max_user_number": 100,
    "emrConfigId": null,
    "createdAt": "date",
    "updatedAt": "date",
    "workspacetiers": [
      {
        "isSingleUser": false,
        "id": 123,
        "name": "name",
        "workspaceId": 123,
        "startsAt": "date"
      }
    ]
  },
  {
    "id": 456,
    "name": "workspace1",
    "state": "active",
    "lastStateChange": null,
    "deleted_at": null,
    "custom_url": "url",
    "max_user_number": 100,
    "emrConfigId": null,
    "createdAt": "date",
    "updatedAt": "date",
    "workspacetiers": [
      {
        "isSingleUser": false,
        "id": 456,
        "name": "name",
        "workspaceId": 456,
        "startsAt": "date"
      }
    ]
  }
]

Pick out the workspace you want to invite the users to and note its ID. For this example, use the <id> value for one of the workspaces.

Next, invite new users to this workspace with this example:

Important

Be sure to fill in your workspace ID for <id> and your token for <token>.

curl -X POST 'https://us1.alteryxcloud.com/v4/workspaces/<id>/people/batch' \
-H 'Content-type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{"emails": ["name1@domain.com", "name2@domain.com>"]}'

At this point, curl doesn’t display anything on success. By default, curl only shows the response body. Add -v to the above command for verbose output.

Congratulations you’ve now added users to a workspace! If the above command executed successfully, your new users will receive emails inviting them to join AAC.

In this section: