Skip to main content

Server API Overview

Importante

If you are new to APIs, visit the Get Started with APIs help page.

Importante

Starting with the 22.1 release, we removed our legacy public OAuth1 API endpoints because they require non-FIPS compliant SHA1 hashing. This removal includes the legacy WCF (Windows Communication Framework) endpoints, Swagger for these legacy endpoints, and OAuth1 middleware. To replace the OAuth1 endpoints, you can use the OAuth2 versions of the legacy APIs released in 21.4 which are FIPS compliant. You will experience the same functionality with the OAuth2 APIs as you did with the OAuth1 APIs.

Subscription, V1, and V2 endpoints will continue to be supported under OAuth2.

To find out more about the conversion and its impact, visit the OAuth1 to OAuth2 Instructions help page or Conversion Instructions.

The Server API is made up of 6 APIs:

  • Subscription API: Endpoints for users to interact with subscriptions, workflows, and schedules (jobs).

  • User V2 API: Endpoints for users to interact with credentials, input files, and schedules (jobs).

  • Admin V1 API: Endpoints for admins to fetch resources from the Admin interface.

  • Admin V2 API: Version 2 of the endpoints for admins to fetch resources from the Admin interface.

  • Admin V3 API: Version 3 of the endpoints for admins. This version uses OAuth 2.

  • User V3 API: Version 3 of the endpoints for users. This version uses OAuth 2.

Nota

In addition to adding new functionality with V3 API endpoints, we’ve also made our V1, subscription, and V2 endpoints available for use with OAuth 2. The same endpoints you have used in the past are now available for OAuth 2 at a new base address.

The Web API Address can be set up only for V1, V2, and V3 using the OAuth 2.

The Web API address can be set up in System Settings.

For the legacy endpoints using the OAuth1 (V1 and V2 API documentation), the address is http://{ServerHostname}/gallery/api-docs/.

Access Server API Reference Docs

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

There are 2 places in the Server UI where you can access the Server API Reference documentation.

  1. Select the question mark icon in the top toolbar and select API Documentation.

    Thumbnail
  2. Select your username and select My Profile > Keys. You can find links to the API documentation next to the API keys.

You can also access the API reference documentation for the Server API using this URL: http(s)://serverhostname.domain/webapi/swagger. Serverhostname is the URL to your Server instance.

Authenticating to the Server API Reference Docs

The Server API docs are interactive, allowing you to populate parameters and see the responses. To make use of the interactivity, you have to authenticate. To do so, follow these steps:

  1. In the Server UI, select your username and select My Profile > Keys. Copy the API keys for the API you want to authenticate to and paste them in the API Key and Shared Secret fields. The keys will show as Saved.

  2. Select the call you want to run, populate the parameters, and select Try it out.

API Keys and API Access

Curators (Server admins) have to allow users access to the API. Visit Allow User Access to the Server API for more info. Once you have granted user access to the API, users can find their API keys on the Keys tab of the My Profile page. To access your API keys, select your username and select My Profile > Keys.

API keys are located under My Profile Keys.

Users with the Curator role can use the API Access keys to access all APIs.

All non-Curator users can use the API Access keys to access the Subscription API, User V2 API, and User V3 API.

Constructing API Endpoints

To construct an API endpoint use this schema: {Server domain name or alias}/webapi/{endpoint}. For example, if the base address in system settings is https://my.server.tld/gallery you have to prepend each endpoint in the API documentation with https://my.server.tld/webapi.

Authentication

Authentication With OAuth2

Server API that uses the OAuth 1.0a standard for authentication has been deprecated post version 2021.4. For more information about this change, see the Important section at the top of this page.

You can write a script using the OAuth2 method:

  1. Send API Key and Secret to http://[Server host name]/webapi/oauth2/token to get access token.

  2. Send the access token requesting the API endpoint you want to get resources from.

The script depends on the programming language you use (for example, cURL, Python, and so on).

Example: Two-Step Process Using the Python Requests Library

  1. To get an access token, send API Key and Secret to http://[Server host name]/webapi/oauth2/token. See the OAuth2 Web Application Flow in the Python Requests-Oauthlib documentation.

  2. Use the access token returned in the previous step to send the request for resource to the desired API endpoint.

Here is an example of a request to get Server job details from the /v1/jobs/{id} endpoint:

import requests

url = "<http://[server_domain_name]/webapi/v1/jobs/[job ID]?includeMessages=<boolean>>"

payload = {}
headers = {
  'Accept': 'application/json',
  'Authorization': 'Bearer [access token]'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)

For more information on how to authenticate using OAuth2, see the Server API Configuration and Authorization help page.

Authentication With OAuth1

For Server API that uses the OAuth 1.0a standard for authentication, the Server API only requires the signature generation, sometimes called a 1-legged flow, rather than the full, 3-legged OAuth 1.0a flow. See the Signing Process section of the OAuth 1.0a specification for information.

Use a 3rd-party signature generation code that uses the OAuth 1.0a standard to generate these tokens that are required in every API call. Any additional parameters starting with oauth_ are ignored.

  • oauth_consumer_key="{consumer key}"

  • oauth_signature_method="HMAC-SHA1"

  • oauth_signature="{signature}"

  • oauth_timestamp="{timestamp}"

  • oauth_nonce="{nonce}"

  • (optional) oauth_version="1.0"

For enhanced security, we recommend that you send OAuth parameters as headers. Here is an example of a signed cURL request with all the generated tokens passed in an authorization header.

curl --location --request POST 'http:{yourhostname}/api/user/v2/workflows' \
--header 'Authorization: OAuth oauth_consumer_key="{consumer key}",
                         oauth_signature_method="HMAC-SHA1",
                         oauth_signature="{signature}",
                         oauth_timestamp="{timestamp}",
                         oauth_nonce="{nonce}"' \

You can reference a fully-functional sample Server client in C# or JavaScript.

API Endpoints and Parameters

In this section you'll find more information about the following endpoints:

Server tracks changes to these system entities:

  • AppInfo (Workflow)

  • Collection

  • Credential

  • Subscription

  • User

  • UserGroup

Get Logged Events via the Server API

Any updates to these entities triggers the creation of an AuditEvent record. You can return these records via a public Admin API endpoint.

Audit logs are triggered by the following type of operations (events): Update, Insert, and Delete.

Endpoint

The endpoint for AuditEvents is GET /admin/v1/auditlog/

Required Query Parameters

  • entity: (string) the audit log entity you want to query.

  • page: (int) The page you want to return.

  • pageSize: (int) The number of records you want to return on each page.

The response will be an array of Audit Event records:

[
  {
    "id": "",
    "entity": "",
    "entityId": "",
    "userId": "",
    "timestamp": "Date",
    "event": "",
    "oldValues": "",
    "newValues": ""
  }
]

The returned properties are defined below:

  • id: The Audit Event ID.

  • entity: The name of the entity.

  • entityId: The entity ID of the entity.

  • userId: The ID of the user who modified the entity.

  • timestamp: Date and Time of when the Audit Event record was created.

  • event: The event which occurred (insert, update, delete).

  • oldValues: The values of the updated properties prior to the update occurring.

  • newValues: The values of the updated properties after the update has occurred.

To run workflows that use theFile Browse toolvia the API, use the/user/v2/inputfilesendpoint to upload the file.

  1. Start by making a multipart/form-data POST request to the /user/v2/inputfiles endpoint to publish a temporary file. The name of the required form-data section is inputFile.

    curl --location --request POST 'http:{yourhostname}/api/user/v2/inputfiles/' \
    --form 'inputFile=@/file/path/filename.csv' 
  2. Next, make a POST to the /user/v2/workflows/{appId}/jobs/ endpoint.

    1. Then include the name of the File Browse tool in the question object. If you are unsure of the File Browse tool's name, use the /v1/workflows/{appId}/questions endpoint to get your File Browse tool's name.

    2. The value is the reference ID that your input file's call returned in the response.

    curl --location --request POST 'http:{yourhostname}/api/user/v2/workflows/{appId}/jobs' \
    --header 'Content-Type: text/plain' \
    --header 'Authorization: OAuth oauth_consumer_key="{consumer key}",
                             oauth_signature_method="HMAC-SHA1",
                             oauth_timestamp="{timestamp}",
                             oauth_nonce="{nonce}",
                             oauth_signature="{signature}"' \
    --data-raw '{
        "questions": [
            {
                "name": "File Browse",
                "value": "{reference ID}"
            }
        ]
        "priority": "Low"
    }'
    

Use the migratable endpoint to migrate workflows across Server environments. You can use this to manage workflow deployments during development and testing phases.

To begin, you have to enable workflows for migration. Once you mark workflows for migration, follow these steps to publish them from the source environment into the appropriate subscription (studio) of a target environment.Abilitazione dei flussi di lavoro per la migrazione

Step 1. Get a List of Workflows Ready to Migrate

Next, get a list of workflows ready to migrate using the following endpoint:

  • Environment: Source

  • Method: GET

  • Endpoint:api/admin/v1/workflows/migratable/?subscriptionIds={subscriptionIds}/

Include a comma-separated list of subscriptionIds as a query parameter. Subscription IDs identify a specific studio.

The return is an array of workflows marked as ready to migrate under the specified subscription (studio). If you do not provide subscriptionsIds, the return includes all workflows marked as ready to migrate. The return includes 3 properties: appId, the currently published revisionId, and the subscriptionID the workflow belongs to.

Step 2. Download Workflows from the Source Environment

The following endpoint downloads the workflow as a YXZP file.

  • Environment: Source

  • Method: GET

  • Endpoint:api/admin/v1/{appID}/package/

Include an appID as a path parameter. The return will be a download of the entire workflow as a package.

Step 3. Publish Workflows in the Target Environment

The following endpoint publishes the downloaded workflow to the target environment.

  • Environment: Target

  • Method: POST

  • Endpoint:api/admin/v1/workflows/

Parameters

Parameter

Description

Type

Required

file

The filename of the new workflow.

String

True

name

The new workflow name.

String

True

owner

The owner of the migrated workflow. The email address must exist in the target environment.

String

True

validate

Flag to validate the workflow upon migrating to the target environment.

Boolean

True

isPublic

Flag to set the workflow to public to show in “My Company’s Gallery” in the target environment.

Boolean

True

sourceId

This is the Source environment appId of the to-be-migrated workflow. If a workflow with the same sourceId exists, this replaces that workflow in the target environment. Otherwise, a new workflow will be generated.

(Send an empty string if you do not wish to specify an appID.)

String

True

workerTag

Add a worker tag to the workflow to have a specific worker to run the workflow.

(Send an empty string if you do not wish to specify worker.)

String

True

canDownload

Flag to set the workflow as available for download by other users in the target environment.

Boolean

True

(Optional) Step 4. Reset Migration Setting Workflows in the Source Environment

If you want, you can use the migratable endpoint to toggle the This workflow is ready to be migrated setting on a workflow back to No in the source environment after workflow migration in the target environment.

  • Environment: Source

  • Method: PUT

  • Endpoint:api/admin/v1/workflows/migratable/{appID}/

For more information about all Server API endpoints, see the Server APIs overview.

For more information about the Server API V3 endpoints and parameters, visit the Alteryx Server API V3 help page.

Server APIs

Find the list of all released Server APIs in the table below. If an API is available to users, it is therefore available to admins.

Section

API Endpoint

Version

Admin Release Build

User Release Build

Description

1

Audit Logs

GET /admin/v1/auditlog

v1

9.1

Retrieve audit log entries for a given entity type

2

Collections

GET /v3/collections

v3

2021.4

Retrieve all accessible collection records

3

Collections

POST /v3/collections

v3

2021.4

Create a new collection

4

Collections

DELETE /v3/collections/{collectionId}

v3

2021.4

Delete a collection

5

Collections

GET /v3/collections/{collectionId}

v3

2021.4

Retrieve a collection record

6

Collections

PUT /v3/collections/{collectionId}

v3

2021.4

Update an existing collection to change the name or owner

7

Collections

PUT /v3/collections/{collectionId}/users/

{userId}/permissions

v3

2021.4

Update a collection users permissions

8

Collections

PUT /v3/collections/{collectionId}/userGroups/

{userGroupId}/permissions

v3

2021.4

Update a collection userGroups permissions

9

Collections

POST /v3/collections/{collectionId}/users

v3

2021.4

Add a user to a collection

10

Collections

POST /v3/collections/{collectionId}/insights

v3

2021.4

Add an insight to a collection

11

Collections

POST /v3/collections/{collectionId}/schedules

v3

2021.4

Add a schedule to a collection

12

Collections

POST /v3/collections/{collectionId}/workflows

v3

2021.4

Add a workflow to a collection

13

Collections

POST /v3/collections/{collectionId}/userGroups

v3

2021.4

Add a userGroup to a collection

14

Collections

DELETE /v3/collections/{collectionId}/users/{userId}

v3

2021.4

Remove a user from a collection

15

Collections

DELETE /v3/collections/{collectionId}/workflows/{appId}

v3

2021.4

Remove a workflow from a collection

16

Collections

DELETE /v3/collections/{collectionId}/insights/{insightId}

v3

2021.4

Remove an insight from a collection

17

Collections

DELETE /v3/collections/{collectionId}/

schedules/{scheduleId}

v3

2021.4

Remove a schedule from a collection

18

Collections

DELETE /v3/collections/{collectionId}/

userGroups/{userGroupId}

v3

2021.4

Remove a userGroup from a collection

19

Collections

GET /admin/v1/collections

v1

9.1

Find collections in a Gallery

20

Credentials

GET /v3/credentials/{credentialId}

v3

2021.4

2022.3

Retrieve a credential record

21

Credentials

GET /v3/credentials

v3

2021.4

2022.3

Retrieve credential records

22

Credentials

DELETE /v3/credentials/{credentialId}

v3

2021.4

Delete a credential

23

Credentials

POST /v3/credentials/{credentialId}/users

v3

2021.4

Share a credential with a user

24

Credentials

POST /v3/credentials/{credentialId}/userGroups

v3

2021.4

Share a credential with a userGroup

25

Credentials

DELETE /v3/credentials/{credentialId}/users/{userId}

v3

2021.4

Removes a user from a credential

26

Credentials

DELETE /v3/credentials/{credentialId}/

userGroups/{userGroupId}

v3

2021.4

Removesa userGroup from a credential

27

Credentials

GET /user/v2/credentials

v2

11.3

Find credentials shared directly with users or via a sub

28

DCMEConnections

GET /v3/DCMEConnections/{connectionId}

v3

2022.1

Retrieve a DCM.E connection

29

Insights

GET /admin/v2/insights

v2

11.3

Find insights in a Gallery

30

Insights

GET /admin/v1/insights

v1

9.1

Find insights in a Gallery

31

Jobs

GET /v3/jobs/id

v3

2022.3

2022.3

Retrieve the job and its current state

32

Jobs

POST /user/v2/workflows/{appId}/jobs

Nota

If the workflow was published with a Credential, a Shared Credential must be explicitly applied in the API call.

v2

11.3

11.3

Create a new job and adds it to the job execution queue

33

Jobs

GET /v1/jobs/{id}/output/{outputId}

v1

9.1

9.1

Get output for a given job

34

Jobs

GET /v1/jobs/{id}

v1

9.1

9.1

Retrieve the job and its current state

35

Jobs

GET /v1/workflows/{appId}/jobs

v1

9.1

9.1

Return the jobs for the given Alteryx Analytics App

36

Jobs

POST /v1/workflows/{appId}/jobs

Nota

Use POST /user/v2/workflows/{appId}/jobs if the workflow needs a Credential to run.

v1

9.1

9.1

Queue a job execution for the specified workflow with the supplied answers

37

Jobs

GET /admin/v1/workflows/jobs

v1

9.1

Return the last run job and its current state for workflows

38

Schedules

DELETE /v3/schedules/{id}

v3

2021.4

Delete a schedule

39

Schedules

GET /v3/schedules/{id}

v3

2021.4

Get information for a specific schedule

40

Schedules

PUT /v3/schedules/{id}

v3

2021.4

Update an existing schedule

41

Schedules

GET /v3/schedules

v3

2021.4

Get all schedules

42

Schedules

POST /v3/schedules

v3

2021.4

Create a new schedule

43

Schedules

GET /admin/v2/schedule/forecast

v2

11.3

Forecast all future run jobs for the given time period

44

Schedules

GET /admin/v1/schedules

v1

9.1

Find schedules in a Gallery

45

Server Connections

GET /v3/serverDataConnections

v3

2021.4

Retrieve all Server data connection records

46

Server Connections

DELETE /v3/serverDataConnections/{dataConnectionId}

v3

2021.4

Delete a Server data connection

47

Server Connections

GET /v3/serverDataConnections/

{dataConnectionId}

v3

2021.4

Retrieve a Server data connection record

48

Server Connections

PUT /v3/serverDataConnections/

{dataConnectionId}

v3

2021.4

Update an existing Server data connection to change the connection name

49

Server Connections

POST /v3/serverDataConnections/

{dataConnectionId}/users

v3

2021.4

Add a user to an existing Server data connection

50

Server Connections

POST /v3/serverDataConnections/

{dataConnectionId}/userGroups

v3

2021.4

Add a userGroup to an existing Server data connection

51

Server Connections

DELETE /v3/serverDataConnections/

{dataConnectionId}/users/{userId}

v3

2021.4

Remove a user from an existing Server data connection

52

Server Connections

DELETE /v3/serverDataConnections/

{dataConnectionId}/userGroups/{userGroupId}

v3

2021.4

Remove a userGroup from an existing Server data connection

53

Server Connections

GET /admin/v1/serverdataconnections

v1

9.1

Return data connections created in a private Gallery

54

Subscriptions

GET /admin/v2/subscriptions

v2

11.3

Find subscriptions in a Gallery

55

Subscriptions

GET /admin/v1/subscriptions

v1

9.1

Find subscriptions in a Gallery

56

System Alias

GET /admin/v1/systemdataconnections

v1

9.1

Return system data connections created on the server where Alteryx Server is installed

57

User Groups

GET /v3/usergroups

v3

2021.4

Get all Customer userGroups

58

User Groups

POST /v3/usergroups

v3

2021.4

Create a new Custom userGroup

59

User Groups

DELETE /v3/usergroups/{id}

v3

2021.4

Delete a Custom userGroup from the system

60

User Groups

GET /v3/usergroups/{id}

v3

2021.4

Retrieve a Custom userGroup

61

User Groups

PUT /v3/usergroups/{id}

v3

2021.4

Update a userGroup’s name and role

62

User Groups

POST /v3/usergroups/{id}/users

v3

2021.4

Add one or more users to a userGroup

63

User Groups

POST /v3/usergroups/{id}/activedirectorygroups

v3

2023.1

Add an Active Directory group as a member of a Server custom group

64

User Groups

DELETE /v3/usergroups/{userGroupId}/users/{userId}

v3

2021.4

Add an Active Directory group as a member of a Server custom group

65

User Groups

DELETE /v3/usergroups/{userGroupID}/

activedirectorygroups/{adGroupSid}

v3

2023.1

Remove an Active Directory group from being a member of a Server custom group

66

Users

DELETE /v3/users/{id}

v3

2021.4

Delete a user from the system

67

Users

GET /v3/users/{id}

v3

2021.4

Retrieve a user record

68

Users

GET /v3/users/{id}/assets

v3

2021.4

Retrieve a full list of assets that a user owns

69

Users

GET /v3/users

v3

2021.4

Search for user records

70

Users

POST /v3/users

v3

2021.4

Create a new user record

71

Users

POST /v3/users/{id}/deactivate

v3

2021.4

Deactivate a user in the system

72

Users

POST /v3/users/{id}/passwordReset

v3

2021.4

Send a password reset email to the given user

73

Users

PUT /v3/users/{id}

v3

2021.4

Update an existing user

74

Users

GET /admin/v2/users

v2

11.3

Find users in a Gallery

75

Users

GET /admin/v1/users

v1

9.1

Finds users in a Gallery

76

Workflows

GET /v3/workflows/{workflowId}

v3

2021.4

2022.3

Retrieve a workflow record

77

Workflows

GET /v3/workflows/{workflowId}/package

v3

2022.3

2022.3

Download a workflow package

78

Workflows

GET /v3/workflows/{workflowId}/questions

v3

2022.3

2022.3

Retrieve question information for a workflow

79

Workflows

GET /v3/workflows/{workflowId}/jobs

v3

2022.3

2022.3

Get a list of jobs for a particular workflow/app

80

Workflows

GET /v3/workflows

v3

2021.4

2022.3

Retrieve all workflow records

81

Workflows

POST /v3/workflows

v3

2021.4

2022.3

Upload a new workflow

82

Workflows

DELETE /v3/workflows/{workflowId}

v3

2021.4

Delete a specific workflow

83

Workflows

PUT /v3/workflows/{workflowId}

v3

2021.4

Update an existing workflow

84

Workflows

POST /user/v2/inputfiles

v2

2020.3

2020.3

Publish a temp file to be used in a subsequent workflow execution

85

Workflows

GET /admin/v2/workflows/all

v2

11.3

Return all workflows, optionally filtered by date

86

Workflows

GET /v1/workflows/{appId}/package

v1

9.1

9.1

Return the app that was requested

87

Workflows

GET /v1/workflows/{appId}/questions

v1

9.1

9.1

Get the questions for the given Alteryx Analytics App

88

Workflows

GET /v1/workflows/subscription

v1

9.1

9.1

Find workflows in a subscription

89

Workflows

GET /admin/v1/{appId}/package

v1

9.1

Return the app that was requested

90

Workflows

GET /admin/v1/workflows/migratable

v1

9.1

Find workflows in a Gallery that have been marked ready for migration

91

Workflows

GET /admin/v1/workflows/all

v1

9.1

Return all workflows, optionally filtered by date

92

Workflows

GET /admin/v1/workflows

v1

9.1

Find workflows in a Gallery

93

Workflows

POST /admin/v1/workflows

v1

9.1

Publishe a YXZP to the system

94

Workflows

PUT /admin/v1/workflows/migratable/{appId}

v1

9.1

Update an App’s ready for migration flag

95

Workflows

POST /v3/workflows/{workflowId}/versions

v3

2023.1

2023.1

Upload a new version to an existing workflow