Alteryx Analytics Hub API Overview

Version:
Current
Last modified: September 28, 2020

Do not delete this has styles that are applied to the article.

Important Disclaimer

The Alteryx Analytics Hub (AAH) API is currently a preview feature. Preview features are available for testing and experimentation, with the goal of gathering feedback. We encourage you to use the AAH API to test and experiment, but it is not intended for production use. As we gather feedback and continue to iterate, the API will change over time, possibly in ways that break backward compatibility. We plan to document all breaking changes to best support your ongoing AAH API use and integration plans.

Access AAH API Reference Docs

The complete reference documentation for all AAH API endpoints is available in Swagger. 

Screenshot of AAH API Swagger Documentation
  1. To access the Swagger reference documentation for the AAH API, go to this URL: {yourhostname}/api-docs (yourhostname is the URL to your Alteryx Analytics Hub instance).
  2. Scroll to the Authenticate Router section of the Swagger documentation.
  3. Select the POST /api/v1/authenticate endpoint.
  4. Select Try it out.
  5. Configure the request body:
    1. Specify an email and password for an AAH user.
    2. In siteName or siteId specify the site name or site ID for the site you want to authenticate to and use while exploring the documentation.
      {
          "email":"platformadmin@example.com",
          "password":"password",
          "siteName":"My Company Site"
      }
  6. Select Execute.

The Swagger reference documentation automatically stores the ayxSession cookie for you so you are authenticated until the cookie expires after 24 hours.

Understanding AAH API Access

All Alteryx Analytics Hub (AAH) users have access to the API. The resources and methods you have access to are determined by the role assigned to the user whose credentials are used to authenticate to the API. For example, a user with the consumer role does not have access to the workflows, schedules, and groups resources and has limited access to the users resource.

Authentication

Authentication in the AAH API is handled via sessions. To get started with the AAH API, make a POST call to the authentication endpoint with your email, password, and the siteName or siteId. If you are a platform admin you can authenticate to platform admin site using "siteName":"platform".

curl --location --request POST 'https://{yourhostname.com}/api/v1/authenticate' \
--header 'Content-Type: application/json' \
--data-raw '{
	"email":"siteadmin1@example.com",
	"password":"Passw0rd!",
	"siteName":"june"
}'

In the response, the ayxSession is included in the Set-Cookie response header. Include this cookie in later calls. The ayxSession cookie expires after 24 hours.

url -v location —request GET 'https://{yourhostname.com}/api/v1/users'
--header 'Content-Type: application/json' 
-b 'ayxSession={ayxSession}'

The Swagger API reference documentation and tools like Postman automatically store this cookie for you.

How the Site You Authenticate to Affects Access to API Resources

The AAH API has both site-level and platform-level resources. It is important to understand how the site you authenticate to affects which site is updated and the resources you have access to.

Site-Level Resources

Site-level resources update the site you are authenticated to. Site-level resources include these:

  • Job
  • RDBMS
  • Schedule
  • Connections
  • Datasources
  • VFS
  • Directory Server
  • Group
  • Workflow
  • Credentials

There are also 4 platform-level resources that are accessible when authenticated to the API as a site admin, as well as, to platform admins authenticated to the platform site. Platform resources that are accessible to both platform and site admins are...

  • User
  • Role
  • Group
  • Platform

Platform-Level Endpoints

Platform-level resources update the Platform Admin site.

For these resources, you have to authenticate with platform admin credentials to the platform site to access them.

Platform-level resources include these:

  • User
  • Role
  • Platform
  • Licenses
  • Identity Provider
  • Site
  • Worker
  • Group

Keep in mind that access to all endpoints is determined by the role assigned to the user whose credentials were used to authenticate.

Get Started with the AAH API

This getting started guide runs through a common user flow to get familiar with the Alteryx Analytics Hub (AAH) API. The examples use cURL calls. This getting started guide assumes you are authenticated as a platform admin to the platform site.

Getting Started API User Flow

  1. Authenticate.
  2. Create a site.
  3. Add users to the platform.
  4. Add users to the site.
  5. Publish a workflow to the site.
  6. Share the published workflow.
  7. Run the workflow.
  8. Schedule the workflow.
  9. Delete the schedule.

Prerequisites

To use the AAH API, you need an Alteryx Analytics Hub account. This getting started guide assumes you are authenticated as a platform admin to the platform site unless specified otherwise.

Authenticate

Begin by authenticating to the AAH API. See Authentication.

Create a Site

Make a post call to the api/v1/sites endpoint.

Properties

  • name: (Required) The site name.
  • adminIds: The user IDs for each user you want to give admin permissions to for the site.

To add additional site admins after site creation, use the api/v1/users/site/{id}/users endpoint and specify the site admin role ID.

curl --location --request POST 'https://{yourhostname.com}/api/v1/sites' \
--header 'X-Auth-Token: ' \
--header 'Content-Type: application/json' \
--data-raw '{
  "site": {
    "name": "New Site",
    "adminIds": [
      "d789bfe5-251b-4139-b2e8-4f97ec57d01a"
    ]
  }
}'

Add Users to the Platform

To add users to your new site, first add them to the platform and make a subsequent call to add them to a site.

TIP

Before you create users, check the api/v1/licenseStatus endpoint to confirm there are available license seats for your new users.

Properties

  • user: (Required) User object.
    • firstName: (Required) The user's first name.
    • lastName: (Required) The user's last name.
    • userName: (Required) The user's AAH username.
    • email: (Required) The user's email address.
  • addLicenseSeat: Set to true to assign a license seat.
  • shouldEmail: Set to true to send the welcome email with AAH activation link to the user. Note, SMTP has to be set up.
curl --location --request POST 'https://{yourhostname.com}/api/v1/platform/users' \
--header 'X-Auth-Token: ' \
--header 'Content-Type: application/json' \
--data-raw '{
  "user": {
    "firstName": "Jane",
    "lastName": "Doe",
    "userName": "JaneDoe",
    "email": "jane.doe@example.com"
  },
  "addLicenseSeat": true,
  "shouldEmail": false
}'

Add Users to the Site

Once you have added users to the platform you can then use the api/v1/users/site/{id}/users endpoint to add them to a site.

Tip

You can also use the /api/v1/users/addUsersToSite endpoint to add users to a site when you are authenticated to the site you want to add users to.

Properties

  • userIds: (Required) The user IDs for the users you want to add to the site.
  • roleIds: (Required) The role ID for the role you want to assign to the user for the site. A user can only have one role per site. You can assign the same role to multiple users in one call. To assign varied user roles, make a call per role. Use the api/v1/platform/roles/ endpoint fetch roleIds.
curl --location --request POST 'https://{yourhostname.com}/api/v1/sites/{id}/users' \
--header 'X-Auth-Token: ' \
--header 'Content-Type: application/json' \
--data-raw '{
  "userIds": [
    "da20e372-0b46-4976-8047-f198fc0fe5e7",
    "004bf15a-0cc3-42c2-9361-c44b456131d7"
  ],
  "roleIds": [
    "23a3649b-9565-4aa1-88cb-a1c7e42c7616"
  ]
}'

Publish a Workflow to the Site

To publish a workflow you have to be authenticated to the site where you want to upload your workflow as the api/v1/files endpoint is a site-level endpoint. Once you are authenticated to the site where you want to upload your workflow, make a POST call to the files endpoint.

Header Properties

  • path: (Required) The location where you want to upload the file. Your path should also include the file name and extension.
  • description: A file description.
  • conflict_action: (Required if filename already exists) Indicates what to do if a workflow with the same name already exists. Options are MERGE which overwrites the existing file and CREATE_COPY which appends an integer suffix to the file, for example, filename(1).yxzp.

Body Properties

  • (Required) Specify the file contents in the response body.
curl --location --request POST 'https://{yourhostname.com}/api/v1/files' \
--header 'Accept: application/json' \
--header 'Content-Type: application/octet-stream' \
--header 'path: /aah/file/path/filename.yxzp' \
--header 'description: Description text' \
--header 'conflict_action: CREATE_COPY' \
--data-binary '@/file/path/filename.yxzp'

How to Handle Spaces in FileNAmes

The AAH API accepts file names with spaces and encodes them for you. For example, the file name my file.yxzp will be saved as my%20file.yxzp. While spaces are encoded for you, it is a best practice to URL encode paths yourself to ensure consistency when interacting with files.

Share the Published Workflow

Use the /api/v1/files/assignPermissions endpoint to share the workflow with another user or group on the site.

Properties

  • assetID: (Required) The ID for the asset you want to share.
  • partyType : (Required) 0 for a user and 1 for a group.
  • partyId: (Required) The user ID or the group ID.
  • permissions: (Required) The permissions you want to give to the user or group for this file. Possible permissions are VIEW, DELETE, DOWNLOAD, or EDIT.
curl --location --request POST 'https://{yourhostname}.com/api/v1/files/assignpermissions' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": [
    {
      "permissions": [
        "VIEW"
      ],
      "partyType": 1,
      "partyId": "2255ee29-dc72-43bf-a50b-7c29d897015c"
    }
  ],
  "assetId": "09c61b7e-c102-4be7-9d90-c46e7608adbc"
}'

Run the Workflow

Use the uuid returned in your publish call (POST to api/v1/files) to then run your workflow via the schedules endpoint. The below example cURL call schedules a manual, one-time run.< /p>

Properties

  • schedule: (Required): The schedule object.
    • name: (Required) The schedule/job name.
    • comment: Schedule comment.
    • assetId: (Required) The uuid for the asset.
    • type: The schedule type. immediate is the default.
curl --location --request POST 'https://{yourhostname.com}/api/v1/schedules' \
--header 'Content-Type: application/json' \
--data-raw '{
    "schedule":
    {
        "name":"Example Workflow One-Time Run",
        "comment":"One-time immediate run",
        "assetId":"09c61b7e-c102-4be7-9d90-c46e7608adbc",
        "type":"immediate"
    }
}'

Schedule the Workflow

The schedules endpoint can also be used to create a recurring schedule for the workflow to run. The below example cURL call schedules a monthly run on the 1st of the month.

Properties

  • schedule: (Required): The schedule object.
    • name: (Required) The schedule/job name.
    • comment: Schedule comment.
    • assetId: (Required) The uuid for the asset.
    • type: The schedule type. Possible schedule types are immediate (default), once, recurring, custom, and validation
    • startDate: The schedule start date.
    • endDate: The schedule end date.
    • frequencyInterval: The schedule frequency interval. Possible frequency interval values are manual, once, custom, hourly, daily, weekly, and monthly.
    • frequencyRule: The frequency rule object.
      • rule: The rule object.
        • frequency: The schedule frequency. Possible frequency values are hourly, daily, weekly, and monthly.
        • byDayofMonth: For recurring schedules, the day of the month to run. Possible values are 1-31, and -1 (use to run on the last day of the month).
curl --location --request POST 'https://{yourhostname.com}/api/v1/schedules' \
--header 'Content-Type: application/json' \
--data-raw '{
    "schedule":
    {
        "name":"Example Workflow One-Time Run",
        "assetId":"7a695e15-5143-450a-b61e-76fa26e64500",
        "comment":"One-time immediate run",
        "type": "recurring",
        "startDate": "2020-06-02T14:49:40.000Z",
        "endDate": "2021-01-01T06:59:59.999Z",
        "frequencyInterval": "monthly",
        "frequencyRule": {
            "rule": {
                "frequency": "MONTHLY",
                "byDayOfMonth": [
                    1
                ]
            }
        }
    }
}'

Delete the Schedule

Use the scheduleId to delete the schedule.

curl --location --request DELETE 'https://{yourhostname.com}/api/v1/schedules/{id}' \
--header 'Content-Type: application/json' \
--data-raw ''
Was This Helpful?

Running into problems or issues with your Alteryx product? Visit the Alteryx Community or contact support.