openapi: 3.0.1
info:
  title: Workfront Planning API
  description: >-
    This is WF Planning Service API documentation. WF Planning Service
    is responsible for creating and managing new workspace, field, record, record
    type objects across the Workfront Planning application. 

    * **API paths**:
      * Gateway URL: https://{customer-domain}.my.workfront.com
      * Base path for this API: /maestro/api
      * Example of a complete path for making a call: https://{customer-domain}.my.workfront.com/maestro/api/v1/records/{id}
    * **Required headers**:
      * All calls require the headers `Authorization`, `x-gw-ims-org-id`, and `x-api-key`. For more information on how to obtain these values, see the [authentication tutorial](/guides/gaining_access/).

basePath: /maestro/api

servers:
- url: https://{customer-domain}/maestro/api
  description: Workfront Planning Service Url
tags:
- name: Workspaces
  description: Workspace Controller
- name: Record Types
  description: Record Type Controller
- name: Records
  description: Record Controller
paths:
  "/v1/records/{id}":
    get:
      tags:
      - Records
      summary: Get Record
      description: Retrieve a specific record by its ID along with optional attributes.
      operationId: getRecord
      parameters:
      - name: id
        in: path
        description: ID of the record to be retrieved
        required: true
        schema:
          type: string
      - name: aliased
        in: query
        description: Flag to include alias support
        required: false
        schema:
          type: boolean
      - name: attributes
        in: query
        description: List of attributes to be included in the response
        required: false
        schema:
          type: array
          items:
            type: string
          default:
          - "*"
        example: ALL
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                "$ref": "#/components/schemas/RecordDto"
    put:
      tags:
      - Records
      summary: Update Record
      description: Update an existing record with the given ID and details.
      operationId: updateRecord
      parameters:
      - name: id
        in: path
        description: ID of the record to be updated
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RecordDto"
        required: true
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                "$ref": "#/components/schemas/RecordDto"
    delete:
      tags:
      - Records
      summary: Delete Record by ID
      description: Delete a specific record by its ID.
      operationId: deleteRecord
      parameters:
      - name: id
        in: path
        description: ID of the record to be deleted
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
  "/v1/records":
    post:
      tags:
      - Records
      summary: Create Record
      description: Create a new record with the given details.
      operationId: createRecord
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RecordDto"
        required: true
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                "$ref": "#/components/schemas/RecordDto"
  "/v1/records/search":
    get:
      tags:
      - Records
      summary: Search Records by field values
      description: Search for records based on specific field values.
      operationId: searchRecordsGet
      parameters:
      - name: recordTypeId
        in: query
        description: Id of the record type
        required: false
        schema:
          type: string
      - name: recordTypeAlias
        in: query
        description: Alias of the record type
        required: false
        schema:
          type: string
      - name: aliased
        in: query
        description: Flag to include alias support
        required: false
        schema:
          type: boolean
      - name: filters
        in: query
        description: Filters
        required: false
        schema:
          type: string
      - name: groupingFieldIds
        in: query
        description: Grouping field ids
        required: false
        schema:
          type: array
          items:
            type: string
      - name: offset
        in: query
        description: Offset
        required: false
        schema:
          type: integer
          format: int32
          default: 0
      - name: limit
        in: query
        description: Limit
        required: false
        schema:
          type: integer
          format: int32
          default: 500
      - name: rowOrderViewId
        in: query
        description: Row order view id
        required: false
        schema:
          type: string
      - name: attributes
        in: query
        description: List of attributes to be included in the response
        required: false
        schema:
          type: array
          items:
            type: string
          default:
          - "*"
        example: ALL
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                "$ref": "#/components/schemas/GroupedRecordsDto"
    post:
      tags:
      - Records
      summary: Search Records by field values
      description: Search for records based on specific field values.
      operationId: searchRecordsPost
      parameters:
      - name: recordTypeAlias
        in: query
        description: Alias of the record type
        required: false
        schema:
          type: string
      - name: aliased
        in: query
        description: Flag to include alias support
        required: false
        schema:
          type: boolean
      - name: attributes
        in: query
        description: List of attributes to be included in the response
        required: false
        schema:
          type: array
          items:
            type: string
          default:
          - "*"
        example: ALL
      requestBody:
        content:
          application/json:
            schema:
              "$ref": "#/components/schemas/RecordSearchDto"
        required: true
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                "$ref": "#/components/schemas/GroupedRecordsDto"
  "/v1/workspaces":
    get:
      tags:
      - Workspaces
      summary: Get All Workspaces
      description: Retrieve a list of all workspaces along with optional attributes.
      operationId: getWorkspaces
      parameters:
      - name: attributes
        in: query
        description: List of attributes to be included in the response
        required: false
        schema:
          type: array
          items:
            type: string
          default:
          - "*"
        example: ALL
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                "$ref": "#/components/schemas/WorkspaceListDto"
  "/v1/workspaces/{id}":
    get:
      tags:
      - Workspaces
      summary: Get Workspace
      description: Retrieve a workspace by its ID along with optional attributes.
      operationId: getWorkspace
      parameters:
      - name: id
        in: path
        description: ID of the workspace to be retrieved
        required: true
        schema:
          type: string
      - name: attributes
        in: query
        description: List of attributes to be included in the response
        required: false
        schema:
          type: array
          items:
            type: string
          default:
          - "*"
        example: ALL
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                "$ref": "#/components/schemas/WorkspaceDto"
  "/v1/record-types":
    get:
      tags:
      - Record Types
      summary: Get Record Types of specified Workspace
      description: Retrieve a list of record types associated with a specified workspace.
        If a user has view access to workspaces, they gain visibility into all record
        types.
      operationId: getRecordTypes
      parameters:
      - name: workspaceId
        in: query
        description: ID of the workspace
        required: true
        schema:
          type: string
      - name: attributes
        in: query
        description: List of attributes to be included in the response
        required: false
        schema:
          type: array
          items:
            type: string
          default:
          - "*"
        example: ALL
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                type: array
                items:
                  "$ref": "#/components/schemas/RecordTypeDto"
  "/v1/record-types/{id}":
    get:
      tags:
      - Record Types
      summary: Get Record Type by ID
      description: Retrieve a specific record type by its ID along with optional attributes.
      operationId: getRecordType
      parameters:
      - name: id
        in: path
        description: ID of the record type to be retrieved
        required: true
        schema:
          type: string
      - name: attributes
        in: query
        description: List of attributes to be included in the response
        required: false
        schema:
          type: array
          items:
            type: string
          default:
          - "*"
        example: ALL
      responses:
        '200':
          description: OK
          content:
            "*/*":
              schema:
                "$ref": "#/components/schemas/RecordTypeDto"
components:
  schemas:
    CoverImage:
      type: object
      properties:
        url:
          type: string
        position:
          type: integer
          format: int32
    RecordDto:
      type: object
      properties:
        id:
          type: string
        createdBy:
          type: string
        createdAt:
          type: string
        updatedBy:
          type: string
        updatedAt:
          type: string
        customerId:
          type: string
        imsOrgId:
          type: string
        recordTypeId:
          type: string
        data:
          type: object
          additionalProperties:
            type: object
        recordExternalOptions:
          "$ref": "#/components/schemas/RecordExternalOptions"
        thumbnailUrl:
          type: string
        coverImage:
          "$ref": "#/components/schemas/CoverImage"
    RecordExternalOptions:
      type: object
      properties:
        connection:
          type: string
          enum:
          - WORKFRONT
          - AEM
        object:
          type: string
          enum:
          - PROJECT
          - PORTFOLIO
          - PROGRAM
          - COMPANY
          - GROUP
          - ASSET
        externalId:
          type: string
        connectionOptions:
          type: object
          additionalProperties:
            type: object
        link:
          type: string
    JsonNode:
      type: object
    RecordSearchDto:
      type: object
      properties:
        recordTypeId:
          type: string
        recordTypeAlias:
          type: string
        filters:
          "$ref": "#/components/schemas/JsonNode"
        groupingFieldIds:
          type: array
          items:
            type: string
        sorting:
          type: array
          items:
            "$ref": "#/components/schemas/RecordSorting"
        offset:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
        rowOrderViewId:
          type: string
    RecordSorting:
      type: object
      properties:
        fieldId:
          type: string
        direction:
          type: string
          enum:
          - asc
          - desc
    GroupedRecordsDto:
      type: object
      properties:
        records:
          type: array
          items:
            "$ref": "#/components/schemas/RecordDto"
        groups:
          type: array
          items:
            "$ref": "#/components/schemas/RecordGroupDto"
        totalCount:
          type: integer
          format: int32
    RecordGroupDto:
      type: object
      properties:
        fieldId:
          type: string
        value:
          type: object
        recordIds:
          type: array
          items:
            type: string
    FieldDateOptionsDto:
      type: object
      properties:
        dateFormat:
          type: string
          enum:
          - locale
          - standard
          - friendly
          - european
          - iso
        timeFormat:
          type: string
          enum:
          - h12
          - h24
    FieldDto:
      type: object
      properties:
        id:
          type: string
        createdBy:
          type: string
        createdAt:
          type: string
        updatedBy:
          type: string
        updatedAt:
          type: string
        customerId:
          type: string
        imsOrgId:
          type: string
        alias:
          type: string
        displayName:
          type: string
        type:
          type: string
        linkedField:
          "$ref": "#/components/schemas/FieldDto"
        description:
          type: string
        options:
          type: array
          items:
            "$ref": "#/components/schemas/FieldOptionDto"
        dateOptions:
          "$ref": "#/components/schemas/FieldDateOptionsDto"
        numberOptions:
          "$ref": "#/components/schemas/FieldNumberOptionsDto"
        referenceOptions:
          "$ref": "#/components/schemas/FieldReferenceOptionsDto"
        lookupOptions:
          "$ref": "#/components/schemas/FieldLookupOptionsDto"
        formulaOptions:
          "$ref": "#/components/schemas/FieldFormulaOptionsDto"
        userOptions:
          "$ref": "#/components/schemas/FieldUserOptionsDto"
        hasError:
          type: boolean
    FieldFormulaOptionsDto:
      type: object
      properties:
        formula:
          type: string
    FieldLookupOptionsDto:
      type: object
      properties:
        referenceFieldId:
          type: string
        rollup:
          type: string
        sourceField:
          "$ref": "#/components/schemas/FieldDto"
    FieldNumberOptionsDto:
      type: object
      properties:
        precision:
          type: integer
          format: int32
        allowNegatives:
          type: boolean
        currency:
          type: string
          enum:
          - AED
          - AFN
          - ALL
          - AMD
          - AON
          - ARS
          - AUD
          - AZN
          - BAM
          - BBD
          - BDT
          - BGL
          - BHD
          - BIF
          - BND
          - BOB
          - BRL
          - BSD
          - BTN
          - BWP
          - BYN
          - BZD
          - CAD
          - CDF
          - CHF
          - CLP
          - CNY
          - COP
          - CRC
          - CUP
          - CVE
          - DJF
          - DKK
          - DOP
          - DZD
          - EGP
          - ERN
          - ETB
          - EUR
          - FJD
          - GBP
          - GEL
          - GHC
          - GMD
          - GNF
          - GTQ
          - GYD
          - HNL
          - HRK
          - HTG
          - HUF
          - IDR
          - ILS
          - INR
          - IQD
          - IRR
          - ISK
          - JMD
          - JOD
          - JPY
          - KES
          - KGS
          - KHR
          - KMF
          - KPW
          - KRW
          - KWD
          - KZT
          - LAK
          - LBP
          - LKR
          - LRD
          - LSL
          - LYD
          - MAD
          - MDL
          - MGA
          - MKD
          - MMK
          - MNT
          - MRU
          - MUR
          - MVR
          - MWK
          - MXN
          - MYR
          - MZM
          - NAD
          - NGN
          - NIO
          - NOK
          - NPR
          - NZD
          - OMR
          - PAB
          - PEN
          - PGK
          - PHP
          - PKR
          - PLN
          - PYG
          - QAR
          - RON
          - RSD
          - RUB
          - RWF
          - SAR
          - SBD
          - SCR
          - SDG
          - SEK
          - SGD
          - SLL
          - SOS
          - SRD
          - SSP
          - STN
          - SYP
          - SZL
          - THB
          - TJS
          - TMT
          - TND
          - TOP
          - TRY
          - TTD
          - TZS
          - UAH
          - UGS
          - USD
          - UYU
          - UZS
          - VEF
          - VND
          - VUV
          - WST
          - XAF
          - XCD
          - XOF
          - YER
          - ZAR
          - ZMK
          - ZWD
    FieldOptionDto:
      type: object
      properties:
        name:
          type: string
        displayName:
          type: string
        color:
          type: string
    FieldReferenceExternalOptionsDto:
      type: object
      properties:
        connectionName:
          type: string
        objectName:
          type: string
        connectionOptions:
          type: object
          additionalProperties:
            type: string
    FieldReferenceLookupFieldDto:
      type: object
      properties:
        fieldId:
          type: string
        rollup:
          type: string
    FieldReferenceOptionsDto:
      type: object
      properties:
        multiple:
          type: boolean
        recordTypeId:
          type: string
        isExternal:
          type: boolean
        externalOptions:
          "$ref": "#/components/schemas/FieldReferenceExternalOptionsDto"
        filters:
          type: object
          additionalProperties:
            type: object
        lookupFields:
          type: array
          items:
            "$ref": "#/components/schemas/FieldReferenceLookupFieldDto"
    FieldUserOptionsDto:
      type: object
      properties:
        multipleUsersAllowed:
          type: boolean
    RecordTypeDto:
      type: object
      properties:
        id:
          type: string
        createdBy:
          type: string
        createdAt:
          type: string
        updatedBy:
          type: string
        updatedAt:
          type: string
        customerId:
          type: string
        imsOrgId:
          type: string
        alias:
          type: string
        displayName:
          type: string
        permission:
          type: string
          enum:
          - manage
          - edit
          - view
          - none
        primaryFieldId:
          type: string
        icon:
          type: string
        description:
          type: string
        color:
          type: string
        fields:
          type: array
          items:
            "$ref": "#/components/schemas/FieldDto"
        isExternal:
          type: boolean
        externalOptions:
          "$ref": "#/components/schemas/RecordTypeExternalOptionsDto"
    RecordTypeExternalOptionsDto:
      type: object
      properties:
        connectionName:
          type: string
        objectName:
          type: string
        fields:
          type: object
          additionalProperties:
            type: string
    RecordTypeSectionDto:
      type: object
      properties:
        name:
          type: string
        displayName:
          type: string
        recordTypeIds:
          type: array
          items:
            type: string
    WorkspaceDto:
      type: object
      properties:
        id:
          type: string
        createdBy:
          type: string
        createdAt:
          type: string
        updatedBy:
          type: string
        updatedAt:
          type: string
        customerId:
          type: string
        imsOrgId:
          type: string
        alias:
          type: string
        name:
          type: string
        description:
          type: string
        color:
          type: string
        permission:
          type: string
          enum:
          - manage
          - edit
          - view
          - none
        icon:
          type: string
        recordTypes:
          type: array
          items:
            "$ref": "#/components/schemas/RecordTypeDto"
        recordTypeSections:
          type: array
          items:
            "$ref": "#/components/schemas/RecordTypeSectionDto"
    WorkspaceListDto:
      type: object
      properties:
        workspaces:
          type: array
          items:
            "$ref": "#/components/schemas/WorkspaceDto"
        permission:
          type: string
          enum:
          - manage
          - edit
          - view
          - none