Alteryx Analytics Hub API Overview

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

Access AAH API Reference Docs

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

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.

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.

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.

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/sites/{id}/users endpoint to add them to a site.

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'

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 ''