openapi: 3.2.0
info:
  title: Workfront Planning API Version 2 Fields API
  description: This is Workfront Planning Service API documentation. Workfront Planning Service is responsible for creating and managing new workspace, field, record, record type objects across the Workfront application and Adobe DX infrastructure.
servers:
- url: https://{customer-domain}/maestro/api
  description: Workfront Planning Service Url
tags:
- name: Fields
  description: 'Field management. Per-record-type quotas: max 500 fields total; max 20 PARAGRAPH (long-text) fields; max 20 FORMULA fields; max 30 REFERENCE fields. Field display names must be unique within a record type and capped at 256 characters. Formula expressions: max 50,000 characters; lookup depth: max 5.'
paths:
  /v2/fields/{id}:
    get:
      tags:
      - Fields
      summary: Get Field
      description: Retrieve a field by its ID.
      operationId: getField
      parameters:
      - name: id
        in: path
        description: ID of the field to be retrieved
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
    put:
      tags:
      - Fields
      summary: Update Field
      description: Update an existing field using PUT (full replacement). All fields not provided in the request will be set to null.
      operationId: updateField
      parameters:
      - name: id
        in: path
        description: ID of the field to be updated
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldDto'
        '400':
          description: Bad Request (validation failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '403':
          description: Forbidden (FIELD_DISPLAY_NAME_NOT_UNIQUE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '409':
          description: Conflict (write conflict, retry)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
    delete:
      tags:
      - Fields
      summary: Delete Field
      description: Delete a field by its ID.
      operationId: deleteField
      parameters:
      - name: id
        in: path
        description: ID of the field to be deleted
        required: true
        schema:
          type: string
      responses:
        '204':
          description: No Content
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
    patch:
      tags:
      - Fields
      summary: Patch Field
      description: Partially update a field using PATCH (merge-patch semantics). Only provided fields will be updated; omitted fields remain unchanged.
      operationId: patchField
      parameters:
      - name: id
        in: path
        description: ID of the field to be patched
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldDto'
        '400':
          description: Bad Request (validation failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '403':
          description: Forbidden (FIELD_DISPLAY_NAME_NOT_UNIQUE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '409':
          description: Conflict (write conflict, retry)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
  /v2/record-types/{recordTypeId}/fields:
    get:
      tags:
      - Fields
      summary: Get Fields by Record Type
      description: Retrieve a cursor-paginated list of fields for a specific record type.
      operationId: getFieldsByRecordType
      parameters:
      - name: recordTypeId
        in: path
        description: ID of the record type
        required: true
        schema:
          type: string
      - name: cursor
        in: query
        description: Cursor from the previous page response for fetching the next page
        required: false
        schema:
          type: string
      - name: limit
        in: query
        description: Maximum number of items to return per page (1-100, default 20)
        required: false
        schema:
          type: integer
          format: int32
          default: 20
          maximum: 100
          minimum: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponseFieldDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '404':
          description: Record Type Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
    post:
      tags:
      - Fields
      summary: Create Field
      description: 'Create a new field in a record type. Subject to limits: max 500 fields per record type, max 20 long-text fields, max 20 formula fields, max 30 reference fields per record type.'
      operationId: createField
      parameters:
      - name: recordTypeId
        in: path
        description: ID of the record type
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldDto'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldDto'
        '400':
          description: Bad Request (validation failure)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '403':
          description: Forbidden (FIELD_LIMIT_EXCEEDED, LONG_TEXT_FIELD_LIMIT_EXCEEDED, FORMULA_FIELD_COUNT_LIMIT_EXCEEDED, REFERENCE_FIELDS_COUNT_LIMIT_EXCEEDED, FIELD_DISPLAY_NAME_NOT_UNIQUE)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '404':
          description: Record Type Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
components:
  schemas:
    FieldLookupOptionsDto:
      type: object
      description: Lookup field options
      properties:
        referenceFieldId:
          type: string
          description: Reference field ID
        rollup:
          type: string
          description: Rollup function (e.g., SUM, AVG, COUNT)
        sourceField:
          $ref: '#/components/schemas/FieldDto'
          description: Source field being looked up
    FieldReferenceOptionsDto:
      type: object
      description: Reference field options
      properties:
        multiple:
          type: boolean
          description: Whether multiple records can be selected
        showThumbnail:
          type: boolean
          description: Whether to show thumbnail
        showTitle:
          type: boolean
          description: Whether to show title
        showColor:
          type: boolean
          description: Whether to show color
        recordTypeId:
          type: string
          description: Referenced record type ID
        isExternal:
          type: boolean
          description: Whether the reference is external
        createBackReference:
          type: boolean
          description: Whether to create a back reference
        backField:
          $ref: '#/components/schemas/FieldDto'
          description: Back reference field
        externalOptions:
          $ref: '#/components/schemas/FieldReferenceExternalOptionsDto'
          description: External options for external references
        filters:
          type: object
          additionalProperties: {}
          description: Filters for the reference field
        lookupFields:
          type: array
          description: Lookup fields for the reference
          items:
            $ref: '#/components/schemas/FieldReferenceLookupFieldDto'
        scopeWorkspaceIds:
          type: array
          description: Scope workspace IDs for global record types
          items:
            type: string
        globalRecordTypeWorkspaceFieldId:
          type: string
          description: Global record type workspace field ID
    FieldDateOptions:
      type: object
      properties:
        dateFormat:
          type: string
          enum:
          - locale
          - standard
          - friendly
          - european
          - iso
          - short
          - medium
          - long
        timeFormat:
          type: string
          enum:
          - h12
          - h24
        useSameTimezoneForAllCollaborators:
          type: boolean
        timezoneId:
          type: string
    FieldAttachmentOptionsDto:
      type: object
      description: Attachment field options
      properties:
        showThumbnail:
          type: boolean
          description: Whether to display attachment thumbnails
        showTitle:
          type: boolean
          description: Whether to display attachment titles
    V2ProblemDetail:
      type: object
      description: RFC 7807 Problem Details error response for V2 endpoints.
      properties:
        title:
          type: string
          description: Short, human-readable summary of the error type. Same for all occurrences of the same error.
          example: Not found
        status:
          type: integer
          format: int32
          description: HTTP status code of the response.
          example: 404
        detail:
          type: string
          description: Human-readable, resource-specific explanation of this error occurrence. Always English.
          example: Record type with ID 'Rt69b14f7e' was not found.
        errorCode:
          type: string
          description: Machine-readable error code (enum name).
          example: ENTITY_WITH_ATTRIBUTE_NOT_FOUND
        messageArguments:
          type: object
          additionalProperties:
            type: string
          description: Named parameters used to compose the detail message. Values are always strings.
          example:
            recordTypeId: Rt69b14f7e
        requestId:
          type: string
          description: Request correlation ID for tracing and support.
          example: 5b1f7a8c-2c0e-4a8f-9c4f-2a3b1c0e4d5f
        errors:
          type: array
          description: Field-level or per-item error details. Present for validation, business-rule, or batch failures.
          items:
            $ref: '#/components/schemas/V2FieldError'
      required:
      - detail
      - errorCode
      - requestId
      - status
      - title
    FieldOptionDto:
      type: object
      description: Field option for single-select and multi-select fields
      properties:
        name:
          description: Name identifier for the option
        displayName:
          type: string
          description: Display name for the option
        color:
          type: string
          description: Color code for the option
        groupId:
          type: string
          description: Group ID for grouped options
    FieldMetadataDto:
      type: object
      description: Field metadata
      properties:
        originType:
          type: string
          description: Origin type of the field
        extendedRollup:
          type: string
          description: Extended rollup information
    V2FieldError:
      type: object
      description: Field-level error detail used in validation errors and per-item batch failures.
      properties:
        field:
          type: string
          description: Name of the field or path that caused the error.
          example: name
        message:
          type: string
          description: Human-readable explanation of the error for this field.
          example: Workspace name can not be blank
        code:
          type: string
          description: Machine-readable code identifying the validation rule that failed.
          example: NotBlank
    FieldNumberOptionsDto:
      type: object
      description: Number field options for number, percentage, and currency fields
      properties:
        precision:
          type: integer
          format: int32
          description: Decimal places (0-4)
        allowNegatives:
          type: boolean
          description: Whether negative values are allowed
        currency:
          type: string
          description: Currency code (e.g. USD, EUR, GBP); only for currency fields
          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
        visualizationType:
          type: string
          description: 'Display format: TEXT (default), PROGRESS_BAR, or PROGRESS_CIRCLE'
          enum:
          - TEXT
          - PROGRESS_BAR
          - PROGRESS_CIRCLE
    CursorInfo:
      type: object
      description: Cursor pagination metadata
      properties:
        nextCursor:
          type: string
          description: Opaque cursor for fetching the next page. Absent when there are no more pages.
          example: UnQ2OWIxNGY3ZTBlMzhmMzVmMjhjM2NjZWU=
        hasMore:
          type: boolean
          description: Whether more items exist beyond this page
    FieldDateOptionsDto:
      type: object
      description: Date field options
      properties:
        dateFormat:
          type: string
          description: Date format
          enum:
          - locale
          - standard
          - friendly
          - european
          - iso
          - short
          - medium
          - long
        timeFormat:
          type: string
          description: Time format
          enum:
          - h12
          - h24
    FieldUserOptionsDto:
      type: object
      description: User field options
      properties:
        multipleUsersAllowed:
          type: boolean
          description: Whether multiple users can be selected
    FieldDto:
      type: object
      description: Field data for record types
      properties:
        id:
          type: string
          description: Unique identifier of the field
          example: F693ab1c96f11ea3f4175e716
          readOnly: true
        createdBy:
          $ref: '#/components/schemas/UserReferenceDto'
          description: User who created this entity
          readOnly: true
        createdAt:
          type: string
          description: Date/time when this entity was created
          example: '2026-01-15T10:30:00.000Z'
          pattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
          readOnly: true
        updatedBy:
          $ref: '#/components/schemas/UserReferenceDto'
          description: User who last updated this entity
          readOnly: true
        updatedAt:
          type: string
          description: Date/time when this entity was last updated
          example: '2026-01-15T14:45:00.000Z'
          pattern: yyyy-MM-dd'T'HH:mm:ss.SSS'Z'
          readOnly: true
        alias:
          type: string
          description: Unique alias identifier for the field
          example: campaign_name
          readOnly: true
        displayName:
          type: string
          description: Display name of the field. Maximum 256 characters; must be unique within the parent record type.
          example: Campaign Name
          maxLength: 256
          minLength: 0
        type:
          type: string
          description: 'Type of the field. Subject to per-record-type quotas: max 20 PARAGRAPH (long text), max 20 FORMULA, max 30 REFERENCE.'
          enum:
          - TEXT
          - PARAGRAPH
          - NUMBER
          - PERCENTAGE
          - CURRENCY
          - DATE
          - SINGLE_SELECT
          - MULTI_SELECT
          - CHECKBOX
          - REFERENCE
          - USER
          - FORMULA
          example: TEXT
        description:
          type: string
          description: Description of the field. Maximum 512 characters.
          example: Name of the marketing campaign
          maxLength: 512
          minLength: 0
        linkedField:
          $ref: '#/components/schemas/FieldDto'
          description: Linked field for reference and lookup fields
        options:
          type: array
          description: Field options for single-select and multi-select fields
          items:
            $ref: '#/components/schemas/FieldOptionDto'
        defaultOptions:
          type: array
          description: Default options for single-select and multi-select fields
          items:
            type: string
        dateOptions:
          $ref: '#/components/schemas/FieldDateOptionsDto'
          description: Date field options
        numberOptions:
          $ref: '#/components/schemas/FieldNumberOptionsDto'
          description: Number field options for number, percentage, and currency fields
        referenceOptions:
          $ref: '#/components/schemas/FieldReferenceOptionsDto'
          description: Reference field options
        lookupOptions:
          $ref: '#/components/schemas/FieldLookupOptionsDto'
          description: Lookup field options
        formulaOptions:
          $ref: '#/components/schemas/FieldFormulaOptionsDto'
          description: Formula field options
        userOptions:
          $ref: '#/components/schemas/FieldUserOptionsDto'
          description: User field options
        defaultUsers:
          type: array
          description: Default user option
          items:
            type: string
        attachmentOptions:
          $ref: '#/components/schemas/FieldAttachmentOptionsDto'
          description: Attachment field options
        hasError:
          type: boolean
          description: Indicates if the field has an error
        isHtmlNative:
          type: boolean
          description: Indicates if the long text field is HTML native
        metadata:
          $ref: '#/components/schemas/FieldMetadataDto'
          description: Field metadata
    FieldReferenceLookupFieldDto:
      type: object
      description: Lookup field configuration for reference fields
      properties:
        fieldId:
          type: string
          description: Field ID to auto-create as a lookup from the linked record type
        rollup:
          type: string
          description: 'Optional aggregation function: sum, avg, min, max, or dist'
    UserReferenceDto:
      type: object
      description: Reference to a user with identifier and display name
      properties:
        id:
          type: string
          description: Unique identifier of the user
          example: 1C341E7B682505430A494138@0bd0200063c87f9749412b.e
          readOnly: true
        name:
          type: string
          description: Display name of the user
          example: Jane Doe
          readOnly: true
    FieldFormulaOptionsDto:
      type: object
      description: Formula field options
      properties:
        formula:
          type: string
          description: Formula expression
        returnType:
          type: string
          description: Return type of the formula
          enum:
          - DATE
          - DATETIME
          - NUMBER
          - PERCENTAGE
          - CURRENCY
          - TEXT
          - TEXT_ARRAY
        numberOptions:
          $ref: '#/components/schemas/FieldNumberOptions'
          description: Number options for number-type formulas
        dateOptions:
          $ref: '#/components/schemas/FieldDateOptions'
          description: Date options for date-type formulas
    FieldNumberOptions:
      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
        visualizationType:
          type: string
          enum:
          - TEXT
          - PROGRESS_BAR
          - PROGRESS_CIRCLE
    CursorResponseFieldDto:
      type: object
      description: Cursor-paginated list of fields
      properties:
        content:
          type: array
          description: List of fields in the current page
          items:
            $ref: '#/components/schemas/FieldDto'
        cursor:
          $ref: '#/components/schemas/CursorInfo'
          description: Cursor metadata for fetching subsequent pages
    FieldReferenceExternalOptionsDto:
      type: object
      description: External reference options for external connections
      properties:
        connectionName:
          type: string
          description: Connection name
        objectName:
          type: string
          description: Object name in the external system
        connectionOptions:
          type: object
          additionalProperties:
            type: string
          description: Connection-specific options