openapi: 3.1.0
info:
  title: Alteryx Server API V3 Collections Workflows API
  description: The Alteryx Server API V3 provides administrative capabilities for managing workflows, schedules, users, user groups, credentials, collections, and server connections. It uses OAuth 2 authentication and implements POST, PUT, GET, DELETE, and PATCH operations so administrators can automate tasks and integrate Server with existing API automation tools.
  version: 3.0.0
  contact:
    name: Alteryx Support
    email: support@alteryx.com
    url: https://community.alteryx.com
  license:
    name: Proprietary
    url: https://www.alteryx.com/terms-and-conditions
  termsOfService: https://www.alteryx.com/terms-and-conditions
  x-logo:
    url: https://www.alteryx.com/sites/default/files/alteryx-logo-2021.svg
servers:
- url: https://{serverHostname}/webapi
  description: Alteryx Server instance
  variables:
    serverHostname:
      default: your-server.example.com
      description: Hostname of your Alteryx Server instance
security:
- oauth2: []
tags:
- name: Workflows
  description: Manage workflows including upload, retrieval, update, deletion, versioning, and job execution
paths:
  /v3/workflows:
    post:
      operationId: uploadWorkflow
      summary: Upload a New Workflow
      description: Upload a new workflow package (YXZP file) to the Alteryx Server.
      tags:
      - Workflows
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - name
              - ownerId
              - isPublic
              - isReadyForMigration
              - othersMayDownload
              - othersCanExecute
              - executionMode
              - workflowCredentialType
              properties:
                file:
                  type: string
                  format: binary
                  description: The YXZP workflow package file
                name:
                  type: string
                  description: Name of the workflow
                ownerId:
                  type: string
                  description: ID of the user who will own the workflow
                workerTag:
                  type: string
                  description: Worker tag for execution routing
                districtTags:
                  type: string
                  description: JSON array of district tags
                comments:
                  type: string
                  description: Comments about the workflow
                isPublic:
                  type: boolean
                  description: Whether the workflow is publicly accessible
                isReadyForMigration:
                  type: boolean
                  description: Whether the workflow is ready for migration
                sourceAppId:
                  type: string
                  description: Source application ID for migration tracking
                othersMayDownload:
                  type: boolean
                  description: Whether other users may download the workflow
                othersCanExecute:
                  type: boolean
                  description: Whether other users can execute the workflow
                executionMode:
                  type: string
                  enum:
                  - Safe
                  - SemiSafe
                  - Standard
                  description: The execution mode for the workflow
                hasPrivateDataExemption:
                  type: boolean
                  description: Whether the workflow has a private data exemption
                workflowCredentialType:
                  type: string
                  enum:
                  - Default
                  - Required
                  - Specific
                  description: Type of credential used for workflow execution
                credentialId:
                  type: string
                  description: ID of the credential to use when workflowCredentialType is Specific
                collectionIds:
                  type: string
                  description: JSON array of collection IDs to add the workflow to
                bypassWorkflowVersionCheck:
                  type: boolean
                  description: Whether to bypass workflow version compatibility checking
      responses:
        '200':
          description: Workflow uploaded successfully
          content:
            application/json:
              schema:
                type: string
                description: The ID of the newly created workflow
        '400':
          description: Bad request - invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or missing authentication
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      operationId: getWorkflows
      summary: Retrieve All Workflows
      description: Retrieve information about all workflow records with optional filtering.
      tags:
      - Workflows
      parameters:
      - name: view
        in: query
        description: Level of detail in the response
        schema:
          type: string
          enum:
          - Default
          - Full
          default: Default
      - name: name
        in: query
        description: Filter workflows by name
        schema:
          type: string
      - name: ownerId
        in: query
        description: Filter workflows by owner ID
        schema:
          type: string
      - name: createdAfter
        in: query
        description: Filter workflows created after this date (ISO 8601 format)
        schema:
          type: string
          format: date-time
      - name: createdBefore
        in: query
        description: Filter workflows created before this date (ISO 8601 format)
        schema:
          type: string
          format: date-time
      responses:
        '200':
          description: List of workflow records
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowSummary'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/workflows/{workflowId}:
    get:
      operationId: getWorkflow
      summary: Retrieve a Specific Workflow
      description: Retrieve detailed information about a specific workflow record.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/workflowId'
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowDetail'
        '401':
          description: Unauthorized
        '404':
          description: Workflow not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateWorkflow
      summary: Update an Existing Workflow
      description: Update the properties of an existing workflow.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/workflowId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateWorkflowContract'
      responses:
        '200':
          description: Workflow updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowDetail'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Workflow not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteWorkflow
      summary: Delete a Workflow
      description: Delete a specific workflow from the server.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/workflowId'
      - name: force
        in: query
        description: Force deletion even if workflow has dependencies
        schema:
          type: boolean
          default: false
      responses:
        '200':
          description: Workflow deleted successfully
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Workflow not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/workflows/{workflowId}/versions:
    post:
      operationId: uploadWorkflowVersion
      summary: Upload a New Version of an Existing Workflow
      description: Upload a new version of an existing workflow package.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/workflowId'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - name
              - ownerId
              - othersMayDownload
              - othersCanExecute
              - executionMode
              - makePublished
              - workflowCredentialType
              properties:
                file:
                  type: string
                  format: binary
                  description: The YXZP workflow package file
                name:
                  type: string
                  description: Name of the workflow version
                ownerId:
                  type: string
                  description: ID of the workflow owner
                othersMayDownload:
                  type: boolean
                  description: Whether other users may download
                othersCanExecute:
                  type: boolean
                  description: Whether other users can execute
                executionMode:
                  type: string
                  enum:
                  - Safe
                  - SemiSafe
                  - Standard
                hasPrivateDataExemption:
                  type: boolean
                comments:
                  type: string
                makePublished:
                  type: boolean
                  description: Whether to make this version the published version
                workflowCredentialType:
                  type: string
                  enum:
                  - Default
                  - Required
                  - Specific
                credentialId:
                  type: string
                bypassWorkflowVersionCheck:
                  type: boolean
      responses:
        '200':
          description: Workflow version uploaded successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowDetail'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
        '404':
          description: Workflow not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/workflows/{workflowId}/package:
    get:
      operationId: downloadWorkflowPackage
      summary: Download a Workflow Package
      description: Download the YXZP package file for a specific workflow.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/workflowId'
      - name: versionId
        in: query
        description: Specific version ID to download
        schema:
          type: string
      responses:
        '200':
          description: Workflow package file
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid version ID
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Workflow not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/workflows/{workflowId}/questions:
    get:
      operationId: getWorkflowQuestions
      summary: Retrieve Analytic App Questions
      description: Retrieve question (input) information for an analytic app workflow.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/workflowId'
      - name: versionId
        in: query
        description: Specific version ID
        schema:
          type: string
      responses:
        '200':
          description: List of workflow questions
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowQuestion'
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Workflow not found
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /v3/workflows/{workflowId}/transfer:
    put:
      operationId: transferWorkflow
      summary: Transfer Workflow Ownership
      description: Transfer a specific workflow to a different owner, optionally including associated schedules.
      tags:
      - Workflows
      parameters:
      - $ref: '#/components/parameters/workflowId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ownerId
              - transferSchedules
              properties:
                ownerId:
                  type: string
                  description: ID of the new owner
                transferSchedules:
                  type: boolean
                  description: Whether to also transfer associated schedules
      responses:
        '200':
          description: Workflow transferred successfully
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Workflow not found
        '500':
          description: Internal server error
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    WorkflowDetail:
      type: object
      description: Detailed representation of an Alteryx workflow including versions
      properties:
        id:
          type: string
          description: Unique workflow identifier
          example: abc123
        sourceAppId:
          type: string
          description: Source application identifier
          example: '500123'
        dateCreated:
          type: string
          format: date-time
          description: Date the workflow was created
          example: '2026-01-15T10:30:00Z'
        runCount:
          type: integer
          description: Total number of times the workflow has been executed
          example: 10
        versions:
          type: array
          description: List of workflow versions
          items:
            $ref: '#/components/schemas/WorkflowVersion'
          example: []
        name:
          type: string
          description: Name of the workflow
          example: Example Title
        ownerId:
          type: string
          description: ID of the workflow owner
          example: '500123'
        workerTag:
          type: string
          description: Worker tag for execution routing
          example: example_value
        districtTags:
          type: array
          items:
            type: string
          description: District tags assigned to the workflow
          example: []
        comments:
          type: string
          description: Comments about the workflow
          example: example_value
        isPublic:
          type: boolean
          description: Whether the workflow is publicly accessible
          example: true
        isReadyForMigration:
          type: boolean
          description: Whether the workflow is ready for migration
          example: true
        publishedVersionId:
          type: string
          description: ID of the currently published version
          example: '500123'
        othersMayDownload:
          type: boolean
          description: Whether other users may download the workflow
          example: true
        othersCanViewHistory:
          type: boolean
          description: Whether other users can view execution history
          example: true
        othersCanExecute:
          type: boolean
          description: Whether other users can execute the workflow
          example: true
        hasPrivateDataExemption:
          type: boolean
          description: Whether the workflow has a private data exemption
          example: true
    UpdateWorkflowContract:
      type: object
      description: Contract for updating an existing workflow
      required:
      - name
      - versionId
      - ownerId
      - workerTag
      - districtTags
      - comments
      properties:
        name:
          type: string
          description: Updated workflow name
          example: Example Title
        versionId:
          type: string
          description: Version ID to update
          example: '500123'
        makePublished:
          type: boolean
          description: Whether to make the specified version published
          example: true
        ownerId:
          type: string
          description: Updated owner ID
          example: '500123'
        workerTag:
          type: string
          description: Updated worker tag
          example: example_value
        districtTags:
          type: array
          items:
            type: string
          description: Updated district tags
          example: []
        comments:
          type: string
          description: Updated comments
          example: example_value
        isPublic:
          type: boolean
          example: true
        isReadyForMigration:
          type: boolean
          example: true
        othersMayDownload:
          type: boolean
          example: true
        othersCanExecute:
          type: boolean
          example: true
        executionMode:
          type: string
          enum:
          - Safe
          - SemiSafe
          - Standard
          example: Safe
        hasPrivateDataExemption:
          type: boolean
          example: true
        workflowCredentialType:
          type: string
          enum:
          - Default
          - Required
          - Specific
          example: Default
        credentialId:
          type: string
          example: '500123'
    WorkflowQuestion:
      type: object
      description: An analytic app question (input parameter)
      properties:
        name:
          type: string
          description: Name of the question
          example: Example Title
        questionType:
          type: string
          description: Type of the question input
          example: example_value
        description:
          type: string
          description: Description of the question
          example: A sample description.
        value:
          type: string
          description: Default value
          example: example_value
        multiple:
          type: boolean
          description: Whether multiple selections are allowed
          example: true
        items:
          type: array
          description: Available options for the question
          items:
            type: object
            properties:
              key:
                type: string
              value:
                type: string
          example: []
    WorkflowVersion:
      type: object
      description: A specific version of a workflow
      properties:
        versionId:
          type: string
          description: Unique version identifier
          example: '500123'
        versionNumber:
          type: integer
          description: Sequential version number
          example: 10
        dateCreated:
          type: string
          format: date-time
          description: Date the version was created
          example: '2026-01-15T10:30:00Z'
        uploadSource:
          type: string
          description: Source from which the version was uploaded
          example: example_value
        uploadDate:
          type: string
          format: date-time
          description: Date the version was uploaded
          example: '2026-01-15T10:30:00Z'
        packageWorkflowType:
          type: string
          description: Type of workflow in the package
          example: example_value
        published:
          type: boolean
          description: Whether this version is the published version
          example: true
        comments:
          type: string
          description: Comments about this version
          example: example_value
        runDisabled:
          type: boolean
          description: Whether execution is disabled for this version
          example: true
        executionMode:
          type: string
          enum:
          - Safe
          - SemiSafe
          - Standard
          example: Safe
        workflowCredentialType:
          type: string
          enum:
          - Default
          - Required
          - Specific
          example: Default
        credentialId:
          type: string
          description: Credential ID if workflowCredentialType is Specific
          example: '500123'
        hasPrivateDataExemption:
          type: boolean
          example: true
        othersMayDownload:
          type: boolean
          example: true
        othersCanViewHistory:
          type: boolean
          example: true
        details:
          $ref: '#/components/schemas/WorkflowVersionDetails'
    WorkflowVersionDetails:
      type: object
      description: Metadata details for a workflow version
      properties:
        isAmp:
          type: boolean
          description: Whether the version uses AMP engine
          example: true
        fileName:
          type: string
          description: Name of the workflow file
          example: example_value
        author:
          type: string
          description: Author of the workflow
          example: example_value
        copyright:
          type: string
          description: Copyright information
          example: example_value
        description:
          type: string
          description: Description of the workflow
          example: A sample description.
        name:
          type: string
          description: Display name of the workflow
          example: Example Title
        noOutputFilesMessage:
          type: string
          description: Message shown when no output files are generated
          example: example_value
        outputMessage:
          type: string
          description: Message shown with output files
          example: example_value
        url:
          type: string
          format: uri
          description: Related URL
          example: https://www.example.com
        urlText:
          type: string
          description: Display text for the related URL
          example: https://www.example.com
    WorkflowSummary:
      type: object
      description: Summary representation of an Alteryx workflow
      properties:
        id:
          type: string
          description: Unique workflow identifier
          example: abc123
        sourceAppId:
          type: string
          description: Source application identifier for migration tracking
          example: '500123'
        name:
          type: string
          description: Name of the workflow
          example: Example Title
        ownerId:
          type: string
          description: ID of the workflow owner
          example: '500123'
        dateCreated:
          type: string
          format: date-time
          description: Date the workflow was created (ISO 8601)
          example: '2026-01-15T10:30:00Z'
        publishedVersionNumber:
          type: integer
          description: Version number of the published version
          example: 10
        isAmp:
          type: boolean
          description: Whether the workflow uses AMP engine
          example: true
        executionMode:
          type: string
          enum:
          - Safe
          - SemiSafe
          - Standard
          description: Execution mode for the workflow
          example: Safe
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        message:
          type: string
          description: Human-readable error message
          example: example_value
        errors:
          type: array
          description: Detailed error information
          items:
            type: object
            properties:
              field:
                type: string
              message:
                type: string
          example: []
  parameters:
    workflowId:
      name: workflowId
      in: path
      required: true
      description: Unique identifier of the workflow
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication using API Access Key and API Access Secret obtained from the Server User Interface under the Keys section.
      flows:
        clientCredentials:
          tokenUrl: https://{serverHostname}/webapi/oauth2/token
          scopes: {}
externalDocs:
  description: Alteryx Server API V3 Documentation
  url: https://help.alteryx.com/current/en/server/api-overview/alteryx-server-api-v3.html