Workday WQL API

openapi: 3.1.0
info:
  title: Workday Report Writer Workday WQL API
  description: >-
    Workday Query Language (WQL) API enabling SQL-like querying of Workday data
    through REST endpoints. Allows developers to construct queries using SELECT,
    FROM, WHERE, ORDER BY, and LIMIT syntax to retrieve report data with high
    performance. Supports pagination, data source discovery, and field metadata
    retrieval, controlled via OAuth 2.0 bearer tokens.
  version: v1
  contact:
    name: Workday Support
    url: https://www.workday.com/en-us/company/contact-us.html
  termsOfService: https://www.workday.com/en-us/legal.html
externalDocs:
  description: Workday REST API Documentation
  url: https://community.workday.com/sites/default/files/file-hosting/restapi/index.html
servers:
  - url: https://{hostname}/ccx/api/wql/v1/{tenant}
    description: Workday WQL Production
    variables:
      hostname:
        description: >-
          Workday data center hostname, varies by tenant deployment
        default: wd2-impl-services1.workday.com
      tenant:
        description: Workday tenant name
        default: your-tenant
tags:
  - name: Data Sources
    description: >-
      Discover available data sources (tables) that can be queried using WQL,
      including their fields and filter definitions
  - name: Query Execution
    description: >-
      Execute WQL queries against Workday data sources and retrieve paginated
      results
security:
  - bearerAuth: []
paths:
  /dataSources:
    get:
      operationId: listDataSources
      summary: Workday Report Writer List Available Data Sources
      description: >-
        Retrieve a collection of data sources (tables) available for querying
        with WQL. Each data source represents a queryable entity in the Workday
        data model.
      tags:
        - Data Sources
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Data sources retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of available data sources
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataSource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /dataSources/{dataSourceId}:
    get:
      operationId: getDataSource
      summary: Workday Report Writer Get a Data Source
      description: >-
        Retrieve details about a specific data source including its description
        and available fields for use in WQL queries.
      tags:
        - Data Sources
      parameters:
        - $ref: '#/components/parameters/dataSourceId'
      responses:
        '200':
          description: Data source details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataSource'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /dataSources/{dataSourceId}/fields:
    get:
      operationId: listDataSourceFields
      summary: Workday Report Writer List Data Source Fields
      description: >-
        Retrieve the fields (columns) available in a specific data source.
        These fields can be used in SELECT, WHERE, and ORDER BY clauses of
        WQL queries.
      tags:
        - Data Sources
      parameters:
        - $ref: '#/components/parameters/dataSourceId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Data source fields retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of fields
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataSourceField'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /dataSources/{dataSourceId}/filters:
    get:
      operationId: listDataSourceFilters
      summary: Workday Report Writer List Data Source Filters
      description: >-
        Retrieve the filterable fields available for a specific data source.
        These filters can be used as parameters in WQL WHERE clauses with
        the dataSourceFilter syntax.
      tags:
        - Data Sources
      parameters:
        - $ref: '#/components/parameters/dataSourceId'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Data source filters retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of filters
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/DataSourceFilter'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /data:
    get:
      operationId: executeWqlQuery
      summary: Workday Report Writer Execute a WQL Query
      description: >-
        Execute a Workday Query Language (WQL) query and retrieve paginated
        results. Supports SQL-like syntax with SELECT, FROM, WHERE, ORDER BY,
        and LIMIT clauses. WQL also supports special operators such as
        startsWith, contains, and endsWith for text filtering.
      tags:
        - Query Execution
      parameters:
        - name: query
          in: query
          required: true
          description: >-
            WQL query string using SQL-like syntax. Example:
            SELECT workdayID, fullName FROM workers WHERE
            supervisoryOrganization = 'IT Department' ORDER BY fullName
            LIMIT 100
          schema:
            type: string
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Query executed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WqlQueryResult'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        OAuth 2.0 bearer token obtained from Workday token endpoint.
        Requires the System - Workday Query Language scope.
  parameters:
    dataSourceId:
      name: dataSourceId
      in: path
      required: true
      description: Unique identifier of the data source
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Maximum number of results to return per page
      schema:
        type: integer
        default: 20
        maximum: 100
    offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
  responses:
    BadRequest:
      description: >-
        The WQL query was malformed, contained invalid syntax, or referenced
        a non-existent data source or field
    Unauthorized:
      description: >-
        Authentication credentials are missing or invalid, or the OAuth 2.0
        token lacks the required Workday Query Language scope
    NotFound:
      description: >-
        The specified data source was not found
  schemas:
    DataSource:
      type: object
      description: >-
        A queryable data source (table) in the Workday data model that can
        be used in WQL FROM clauses
      properties:
        id:
          type: string
          description: Unique identifier of the data source
        descriptor:
          type: string
          description: Display name of the data source
        href:
          type: string
          format: uri
          description: API URL for the data source resource
    DataSourceField:
      type: object
      description: >-
        A field (column) within a data source that can be used in WQL
        SELECT, WHERE, and ORDER BY clauses
      properties:
        id:
          type: string
          description: Unique identifier of the field
        descriptor:
          type: string
          description: Display name of the field
        alias:
          type: string
          description: Alias name used to reference the field in WQL queries
        dataType:
          type: string
          description: Data type of the field
          enum:
            - Text
            - Numeric
            - Date
            - DateTime
            - Boolean
            - Currency
            - RichText
        ordinal:
          type: integer
          description: Position index of the field within the data source
        isRequired:
          type: boolean
          description: Whether the field is required for queries
    DataSourceFilter:
      type: object
      description: >-
        A filter definition for a data source that can be used as a
        parameter in WQL WHERE clauses
      properties:
        id:
          type: string
          description: Unique identifier of the filter
        descriptor:
          type: string
          description: Display name of the filter
        alias:
          type: string
          description: Alias name used to reference the filter in WQL queries
        dataType:
          type: string
          description: Expected data type for filter values
        required:
          type: boolean
          description: Whether this filter is required when querying
    WqlQueryResult:
      type: object
      description: >-
        Result set from a WQL query execution containing the matched rows
        and pagination metadata
      properties:
        total:
          type: integer
          description: Total number of rows matching the query
        data:
          type: array
          items:
            type: object
            additionalProperties: true
          description: >-
            Array of result rows where each object contains key-value pairs
            corresponding to the selected fields in the WQL query