API Overview

Important

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

Important

Starting with the 2022.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. This version uses OAuth 2.
User V3 API: Version 3 of the endpoints for users. This version uses OAuth 2.

Note

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. For the V1 and V2 API documentation using the OAuth 1, the address is http://{ServerHostname}/gallery/api-docs/.

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

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.

Select the question mark icon in the top toolbar and select API Documentation.
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:

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.
Select the call you want to run, populate the parameters, and select Try it out.

API Keys and API Access

Curator (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.

Users with the Curator role can use the API Access keys to access all APIs including the Subscription API, the User V2 API, V1 Admin V1 API, V2 Admin V2 API, and V3 API.

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

Authentication

See the Server API Configuration and Authorization article for more information.

Constructing API Endpoints

To construct an API endpoint use this schema: <hostname>/webapi/.

API Endpoints and Parameters

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

Auditlog Endpoint

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.

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.

Inputfiles Endpoint

To run workflows that use the File Browse Tool via the API, use the/user/v2/inputfilesendpoint to upload the file.

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

Next, make a POST to the /user/v2/workflows/{appId}/jobs/ endpoint.

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.
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"
}'

Migratable Endpoint

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.

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 Server APIs.

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 an existing collection.
5	Collections	GET /v3/collections/{collectionId}	v3	2021.4		Retrieve details about an existing collection.
6	Collections	PUT /v3/collections/{collectionId}	v3	2021.4		Update the name and/or owner of an existing collection.
7	Collections	PUT /v3/collections/{collectionId}/users/{userId}/permissions	v3	2021.4		Update a user's permissions within an existing collection.
8	Collections	PUT /v3/collections/{collectionId}/userGroups/{userGroupId}/permissions	v3	2021.4		Update a user group's permissions within an existing collection.
9	Collections	POST /v3/collections/{collectionId}/users	v3	2021.4		Add a user to an existing collection.
10	Collections	POST /v3/collections/{collectionId}/insights	v3	2021.4		Add an insight to an existing collection.
11	Collections	POST /v3/collections/{collectionId}/schedules	v3	2021.4		Add a schedule to an existing collection.
12	Collections	POST /v3/collections/{collectionId}/workflows	v3	2021.4		Add a workflow to an existing collection.
13	Collections	POST /v3/collections/{collectionId}/userGroups	v3	2021.4		Add a user group to an existing collection.
14	Collections	DELETE /v3/collections/{collectionId}/users/{userId}	v3	2021.4		Remove a user from an existing collection.
15	Collections	DELETE /v3/collections/{collectionId}/workflows/{appId}	v3	2021.4		Remove a workflow from an existing collection.
16	Collections	DELETE /v3/collections/{collectionId}/insights/{insightId}	v3	2021.4		Remove an insight from an existing 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 user group from an existing collection.
19	Collections	GET /admin/v1/collections	v1	9.1		Finds collections in a Gallery
20	Credentials	GET /v3/credentials/{credentialId}	v3	2021.4	2022.3	Retrieve details about an existing credential.
21	Credentials	GET /v3/credentials	v3	2021.4	2022.3	Retrieve all accessible credential records.
22	Credentials	DELETE /v3/credentials/{credentialId}	v3	2021.4		Delete an existing credential.
23	Credentials	POST /v3/credentials/{credentialId}/users	v3	2021.4		Share an existing credential with an existing user.
24	Credentials	POST /v3/credentials/{credentialId}/userGroups	v3	2021.4		Share an existing credential with an existing user group.
25	Credentials	DELETE /v3/credentials/{credentialId}/users/{userId}	v3	2021.4		Remove a user's permissions to use an existing credential.
26	Credentials	DELETE /v3/credentials/{credentialId}/userGroups/{userGroupId}	v3	2021.4		Remove a user group's permission to use an existing credential.
27	Credentials	GET /user/v2/credentials	v2	11.3		Finds credentials shared directly with users or via a sub
28	DCME	DELETE /v3/dcm/connections/{id}	v3	2023.2	2023.2	Delete a DCM Connection.
29	DCME	GET /v3/dcm/connections/{id}	v3	2023.2	2023.2	Retrieve a DCM Connection record.
30	DCME	GET /v3/dcm/connections/lookup	v3	2023.2	2023.2	Retrieve a DCM Connection as referenced in workflows.
31	DCME	DELETE /v3/dcm/connections/{id}/sharing/execution	v3	2023.2	2023.2	Unshare a DCM Connection.
32	DCME	PUT /v3/dcm/connections/{id}/sharing/execution	v3	2023.2	2023.2	Share a DCM Connection with specified Users and Groups.
33	DCME	POST /v3/dcm/connections	v3	2023.2	2023.2	Create or update a DCM Connection.
34	DCMEAdmin	DELETE /v3/dcm/admin/connections/{objectId}	v3	2023.2		Delete a DCM Connection.
35	DCMEAdmin	GET /v3/dcm/admin/connections/{objectId}	v3	2023.2		Retrieve a DCM Connection record.
36	DCMEAdmin	GET /v3/dcm/admin/connections	v3	2023.2		Retrieve a list of DCM Connection records.
37	DCMEAdmin	POST /v3/dcm/admin/connections	v3	2023.2		Create or update a DCM Connection on behalf of a user.
38	DCMEAdmin	DELETE /v3/dcm/admin/connections/{objectId}/sharing/execution	v3	2023.2		Unshare a DCM Connection shared for execution.
39	DCMEAdmin	DELETE /v3/dcm/admin/connections/{objectId}/sharing/collaboration	v3	2023.2		Unshare a DCM Connection shared for collaboration.
40	DCMEConnections	GET /v3/DCMEConnections/{connectionId}	v3	2022.1		Retrieve a DCM.E connection
41	Insights	GET /admin/v2/insights	v2	11.3		Finds insights in a Gallery
42	Insights	GET /admin/v1/insights	v1	9.1		Finds insights in a Gallery
43	Jobs	GET /v3/jobs/{jobId}	v3	2022.3	2022.3	Retrieve details about an existing job and its current state.
44	Jobs	POST /user/v2/workflows/{appId}/jobs Note If the workflow was published with a Credential, a Shared Credential must be explicitly applied in the API call.	v2	11.3	11.3	Creates a new job and adds it to the job execution queue
45	Jobs	GET /v1/jobs/{id}/output/{outputId}	v1	9.1	9.1	Get output for a given job
46	Jobs	GET /v1/jobs/{id}	v1	9.1	9.1	Retrieves the job and its current state
47	Jobs	GET /v1/workflows/{appId}/jobs	v1	9.1	9.1	Returns the jobs for the given Alteryx Analytics App
48	Jobs	POST /v1/workflows/{appId}/jobs Note Use POST /user/v2/workflows/{appId}/jobs if the workflow needs a Credential to run.	v1	9.1	9.1	Queues a job execution for the specified workflow with the supplied answers
49	Jobs	GET /admin/v1/workflows/jobs	v1	9.1		Returns the last run job and its current state for workflows
50	Schedules	DELETE /v3/schedules/{scheduleId}	v3	2021.4		Delete an existing schedule.
51	Schedules	GET /v3/schedules/{scheduleId}	v3	2021.4		Retrieve details about an existing schedule.
52	Schedules	PUT /v3/schedules/{scheduleId}	v3	2021.4		Update details of an existing schedule.
53	Schedules	GET /v3/schedules	v3	2021.4		Retrieve all accessible schedule records.
54	Schedules	POST /v3/schedules	v3	2021.4		Create a new schedule.
55	Schedules	GET /admin/v2/schedule/forecast	v2	11.3		Forecasts all future run jobs for the given time period
56	Schedules	GET /admin/v1/schedules	v1	9.1		Finds schedules in a Gallery
57	Server Connections	GET /v3/serverDataConnections	v3	2021.4		Retrieve all accessible Server data connection records.
58	Server Connections	DELETE /v3/serverDataConnections/{dataConnectionId}	v3	2021.4		Delete an existing Server data connection.
59	Server Connections	GET /v3/serverDataConnections/{dataConnectionId}	v3	2021.4		Retrieve details about an existing Server data connection.
60	Server Connections	PUT /v3/serverDataConnections/{dataConnectionId}	v3	2021.4		Update the connection name of an existing Server data connection.
61	Server Connections	POST /v3/serverDataConnections/{dataConnectionId}/users	v3	2021.4		Share an existing Server data connection with an existing user.
62	Server Connections	POST /v3/serverDataConnections/{dataConnectionId}/userGroups	v3	2021.4		Share an existing Server data connection with an existing user group.
63	Server Connections	DELETE /v3/serverDataConnections/{dataConnectionId}/users/{userId}	v3	2021.4		Remove a user's permissions to use an existing Server data connection.
64	Server Connections	DELETE /v3/serverDataConnections/{dataConnectionId}/userGroups/{userGroupId}	v3	2021.4		Remove a user group's permissions to use an existing Server data connection.
65	Server Connections	GET /admin/v1/serverdataconnections	v1	9.1		Returns data connections created in a private Gallery
66	Subscriptions	GET /admin/v2/subscriptions	v2	11.3		Finds subscriptions in a Gallery
67	Subscriptions	GET /admin/v1/subscriptions	v1	9.1		Finds subscriptions in a Gallery
68	System Alias	GET /admin/v1/systemdataconnections	v1	9.1		Returns system data connections created on the server where Alteryx Server is installed
69	User Groups	GET /v3/usergroups	v3	2021.4		Retrieve all accessible user group records.
70	User Groups	POST /v3/usergroups	v3	2021.4		Create a new user group.
71	User Groups	DELETE /v3/usergroups/{userGroupId}	v3	2021.4		Delete an existing user group.
72	User Groups	GET /v3/usergroups/{userGroupId}	v3	2021.4		Retrieve details about an existing user group.
73	User Groups	PUT /v3/usergroups/{userGroupId}	v3	2021.4		Update name and/or role of an existing user group.
74	User Groups	POST /v3/usergroups/{userGroupId}/users	v3	2021.4		Add one or more existing users to an existing user group.
75	User Groups	POST /v3/usergroups/{userGroupId}/activedirectorygroups	v3	2023.1		Add an Active Directory group to an existing user group.
76	User Groups	DELETE /v3/usergroups/{userGroupId}/users/{userId}	v3	2021.4		Remove a user from an existing user group.
77	User Groups	DELETE /v3/usergroups/{userGroupId}/activedirectorygroups/{adGroupSid}activedirectorygroups/{adGroupSid}	v3	2023.1		Remove an Active Directory group from an existing user group.
78	Users	DELETE /v3/users/{userId}	v3	2021.4		Delete an existing user.
79	Users	GET /v3/users/{userId}	v3	2021.4		Retrieve all accessible assets owned by an existing user.
80	Users	GET /v3/users/{userId}/assets	v3	2021.4		Retrieve a full list of assets that a user owns
81	Users	GET /v3/users	v3	2021.4		Retrieve all accessible user records.
82	Users	POST /v3/users	v3	2021.4		Create a new user.
83	Users	POST /v3/users/{userId}/deactivate	v3	2021.4		Update an existing user as inactive.
84	Users	POST /v3/users/{userId}/passwordReset	v3	2021.4		Send a password reset email to an existing user.
85	Users	PUT /v3/users/{userId}	v3	2021.4		Update details of an existing user.
86	Users	GET /admin/v2/users	v2	11.3		Finds users in a Gallery
87	Users	GET /admin/v1/users	v1	9.1		Finds users in a Gallery
88	Workflows	GET /v3/workflows/{workflowId}	v3	2021.4		Retrieve details about an existing workflow.
89	Workflows	GET /v3/workflows/{workflowId}/package	v3	2022.3	2022.3	Download a copy of an existing workflow package.
90	Workflows	GET /v3/workflows/{workflowId}/questions	v3	2022.3	2022.3	Retrieve question information for an analytic app.
91	Workflows	GET /v3/workflows/{workflowId}/jobs	v3	2022.3	2022.3	Retrieve a list of jobs for an existing workflow.
92	Workflows	GET /v3/workflows	v3	2021.4	2022.3	Retrieve all accessible workflow records.
93	Workflows	POST /v3/workflows	v3	2021.4	2022.3	Upload a new workflow package.
94	Workflows	DELETE /v3/workflows/{workflowId}	v3	2021.4		Delete an existing workflow.
95	Workflows	PUT /v3/workflows/{workflowId}	v3	2021.4		Update details of an existing workflow.
96	Workflows	POST /v3/workflows/{workflowId}/versions	v3	2023.1	2023.1	Upload a new version of an existing workflow.
97	Workflows	POST /v3/workflows/{workflowId}/jobs	v3	2023.2	2023.2	Creates a new job and adds it to the job execution queue.
98	Workflows	POST /user/v2/inputfiles	v2	2020.3	2020.3	Published a temp file to be used in a subsequent workflow execution
99	Workflows	GET /admin/v2/workflows/all	v2	11.3		Return all workflows, optionally filtered by date
100	Workflows	GET /v1/workflows/{appId}/package	v1	9.1	9.1	Returns the app that was requested
101	Workflows	GET /v1/workflows/{appId}/questions	v1	9.1	9.1	Get the questions for the given Alteryx Analytics App
102	Workflows	GET /v1/workflows/subscription	v1	9.1	9.1	Finds workflows in a subscription
103	Workflows	GET /admin/v1/{appId}/package	v1	9.1		Returns the app that was requested
104	Workflows	GET /admin/v1/workflows/migratable	v1	9.1		Finds workflows in a Gallery that have been marked ready for migration
105	Workflows	GET /admin/v1/workflows/all	v1	9.1		Return all workflows, optionally filtered by date
106	Workflows	GET /admin/v1/workflows	v1	9.1		Finds workflows in a Gallery
107	Workflows	POST /admin/v1/workflows	v1	9.1		Publishes a YXZP to the system
108	Workflows	PUT /admin/v1/workflows/migratable/{appId}	v1	9.1		Updates an App’s ready for migration flag

In this section: