openapi: 3.2.0
info:
  title: Workfront Planning API Version 2 Views 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: Views
  description: 'View management. Limits: max 100 personal views per record type; max 255 characters for view name.'
paths:
  /v2/views/{id}:
    get:
      tags:
      - Views
      summary: Get View
      description: Retrieve a view by its ID.
      operationId: getView
      parameters:
      - name: id
        in: path
        description: ID of the view to be retrieved
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewDto'
        '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:
      - Views
      summary: Update View
      description: Update an existing view using PUT (full replacement). All fields not provided in the request will be set to null.
      operationId: updateView
      parameters:
      - name: id
        in: path
        description: ID of the view to be updated
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ViewDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewDto'
        '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
          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:
      - Views
      summary: Delete View
      description: Delete a view by its ID.
      operationId: deleteView
      parameters:
      - name: id
        in: path
        description: ID of the view 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:
      - Views
      summary: Patch View
      description: Partially update a view using PATCH (merge-patch semantics). Only provided fields will be updated; omitted fields remain unchanged.
      operationId: patchView
      parameters:
      - name: id
        in: path
        description: ID of the view to be patched
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ViewDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewDto'
        '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
          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}/views:
    get:
      tags:
      - Views
      summary: Get Views by Record Type
      description: Retrieve a cursor-paginated list of views for a specific record type.
      operationId: getViewsByRecordType
      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/CursorResponseViewDto'
        '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:
      - Views
      summary: Create View
      description: 'Create a new view for a record type. Subject to limits: max 100 personal views per record type.'
      operationId: createView
      parameters:
      - name: recordTypeId
        in: path
        description: ID of the record type
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ViewDto'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ViewDto'
        '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 (VIEW_LIMIT_EXCEEDED)
          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:
    ViewDto:
      type: object
      description: View data containing all view properties
      properties:
        id:
          type: string
          description: Unique identifier of the entity
          example: 69a976d02587b929c9e26dfa
          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
        name:
          type: string
          description: Name of the view. Maximum 255 characters; cannot be blank. Each record type allows up to 100 personal views.
          example: My Table View
          maxLength: 255
          minLength: 0
        type:
          type: string
          description: Type of the view (TABLE, TIMELINE, CALENDAR, LIST, GALLERY)
          enum:
          - table
          - timeline
          - calendar
          - list
          - gallery
          example: table
          minLength: 1
          pattern: table|timeline|calendar|list|gallery
        recordTypeId:
          type: string
          description: ID of the record type this view belongs to
          example: Rt69b14f7e0e38f35f28c3ccee
        filter:
          type: array
          description: Filter conditions applied to records in this view
          example: []
          items:
            $ref: '#/components/schemas/FilterNodeDto'
        grouping:
          type: array
          description: Grouping configuration for records in this view
          items:
            $ref: '#/components/schemas/GroupDto'
        sorting:
          type: array
          description: Sorting configuration for records in this view
          items:
            $ref: '#/components/schemas/SortDto'
        metadata:
          $ref: '#/components/schemas/ViewMetadataDto'
          description: View-specific metadata (column widths, date fields, etc.)
        isHidden:
          type: boolean
          description: Whether this view is hidden from the view list
          example: false
        isPublicShared:
          type: boolean
          description: Whether this view is publicly shared via a link
          example: false
          readOnly: true
        isRestricted:
          type: boolean
          description: Whether this view is restricted (limited access for global/dynamic record types)
          example: false
          readOnly: true
      required:
      - name
      - type
    ViewMetadataDto:
      type: object
      description: View metadata containing view-type specific configuration
      properties:
        type:
          type: string
          description: Type of the view metadata (should match view type)
          example: TABLE
        showThumbnail:
          type: boolean
          description: Whether to show thumbnail images in the view
          example: true
        showRecordColoring:
          type: boolean
          description: Whether to show record coloring in the view
          example: false
        columnMetadata:
          type: array
          description: Column metadata for table views (visibility and width)
          items:
            $ref: '#/components/schemas/ColumnMetadata'
        newColumnMetadata:
          type: array
          description: New column metadata for table views (visible fields only)
          items:
            $ref: '#/components/schemas/ColumnMetadata'
        rowOrder:
          type: array
          description: Custom row order for table views (deprecated)
          items:
            type: string
        startDateKey:
          type: string
          description: Field ID of the start date field (required for timeline and calendar views)
          example: F69b14f7e0e38f35f28c3ccee
        endDateKey:
          type: string
          description: Field ID of the end date field (for timeline and calendar views)
          example: F69b14f7e0e38f35f28c3ccef
        timelineScale:
          type: string
          description: Timeline scale type for timeline views
          enum:
          - YEAR
          - QUARTER
          - MONTH
          - WEEK
        cardFieldIds:
          type: array
          description: Field IDs to display on timeline bars or calendar cards
          items:
            type: string
        coloring:
          $ref: '#/components/schemas/Coloring'
          description: Coloring configuration for conditional formatting
        rowHeight:
          type: string
          description: Row height setting for table and calendar views
          enum:
          - SHORT
          - COMPACT
          - MEDIUM
          - TALL
          - FIT_CONTENT
        truncateRecordContent:
          type: boolean
          description: Whether to truncate record content in timeline views
          example: false
        timelineLayout:
          type: string
          description: 'Layout for timeline views: ''stacked'' or ''swimlane'''
          enum:
          - stacked
          - swimlane
          example: stacked
        dynamicFieldMetadata:
          $ref: '#/components/schemas/DynamicFieldMetadataDto'
          description: Dynamic field metadata for global/dynamic record types
    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
    GroupDto:
      type: object
      description: Grouping specification
      properties:
        fieldId:
          type: string
          description: ID or alias of the field to group by
          example: F693ab1c96f11ea3f4175e710
          minLength: 1
        direction:
          type: string
          description: Sort direction for the grouped values (asc or desc). Defaults to asc if omitted.
          enum:
          - asc
          - desc
          example: asc
      required:
      - fieldId
    FilterCondition:
      type: string
      description: Supported filter conditions for record search
      enum:
      - CONTAINS
      - DOES_NOT_CONTAIN
      - IS
      - IS_NOT
      - IS_EMPTY
      - IS_NOT_EMPTY
      - GREATER_THAN
      - GREATER_THAN_OR_EQUAL
      - LESS_THAN
      - LESS_THAN_OR_EQUAL
      - IS_AFTER
      - IS_BEFORE
      - IS_BETWEEN
      - IS_NOT_BETWEEN
      - IS_ANY_OF
      - IS_NONE_OF
      - HAS_ANY_OF
      - HAS_ALL_OF
      - HAS_NONE_OF
      - IS_EXACTLY
    DynamicFieldMetadataDto:
      type: object
      description: Dynamic field metadata for global/dynamic record types
      properties:
        scopeWorkspaceId:
          type: string
          description: Workspace ID this view is scoped to
          example: Ws69b14f7e0e38f35f28c3ccee
        dynamicFieldIds:
          type: array
          description: Field IDs that are workspace-specific (dynamic) in this view
          items:
            type: string
          uniqueItems: true
    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
    CursorResponseViewDto:
      type: object
      description: Cursor-paginated list of views
      properties:
        content:
          type: array
          description: List of views in the current page
          items:
            $ref: '#/components/schemas/ViewDto'
        cursor:
          $ref: '#/components/schemas/CursorInfo'
          description: Cursor metadata for fetching subsequent pages
    GroupColoring:
      type: object
      properties:
        selected:
          type: string
          enum:
          - DEFAULT
          - FIELD
    FilterGroupDto:
      allOf:
      - $ref: '#/components/schemas/FilterNodeDto'
      - type: object
        properties:
          operator:
            $ref: '#/components/schemas/FilterOperator'
            description: Logical operator to combine conditions
          conditions:
            type: array
            description: 'List of filter nodes: leaf conditions or nested groups'
            items:
              $ref: '#/components/schemas/FilterNodeDto'
            minItems: 1
      description: A group of filter conditions combined with a logical operator (AND/OR). Supports recursive nesting for complex filter logic.
      required:
      - conditions
      - operator
    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
    ColumnMetadata:
      type: object
      properties:
        width:
          type: integer
          format: int32
        fieldId:
          type: string
        visibility:
          type: boolean
        aggregationFunction:
          type: string
          enum:
          - SUM
          - AVG
          - MIN
          - MAX
    FilterColoringRule:
      type: object
      properties:
        id:
          type: string
        color:
          type: string
        appliedFilters:
          type: array
          items: {}
    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
    FilterConditionDto:
      allOf:
      - $ref: '#/components/schemas/FilterNodeDto'
      - type: object
        properties:
          fieldId:
            type: string
            description: ID or alias of the field to filter on
            example: F693ab1c96f11ea3f4175e710
            minLength: 1
          condition:
            $ref: '#/components/schemas/FilterCondition'
            description: Filter condition to apply
          value:
            description: Value to compare against. Omit for unary conditions (IS_EMPTY, IS_NOT_EMPTY). Use an array for range conditions (IS_BETWEEN) or multi-value conditions (IS_ANY_OF). For People fields (USER, CREATED_BY, UPDATED_BY, APPROVED_BY), by default plain string values are interpreted as Adobe IMS user IDs when the customer is IMS-migrated; otherwise they are interpreted as Workfront user IDs. To explicitly set the ID type and avoid ambiguity, pass a typed object such as {"id":"63e3b13000078c1795146248182d15dc","idType":"WF"} (use "idType":"IMS" for Adobe IMS IDs).
            example: Active
          matchExternalId:
            type: boolean
            description: When true, values for REFERENCE fields are treated as external connection IDs and resolved to internal record IDs before the search executes. Only valid for external REFERENCE fields (isExternal=true).
      description: A leaf filter condition applied to a single field
      required:
      - condition
      - fieldId
    Coloring:
      type: object
      properties:
        record:
          $ref: '#/components/schemas/RecordColoring'
        group:
          $ref: '#/components/schemas/GroupColoring'
    RecordColoring:
      type: object
      properties:
        selected:
          type: string
          enum:
          - RECORD_TYPE
          - RECORD
          - FIELD
          - GROUP
          - FILTER
          - NONE
        fieldId:
          type: string
        highlightFullRow:
          type: boolean
        filterColoringRules:
          type: array
          items:
            $ref: '#/components/schemas/FilterColoringRule'
    FilterOperator:
      type: string
      description: Logical operator for combining filter conditions
      enum:
      - AND
      - OR
    SortDto:
      type: object
      description: Sort specification
      properties:
        fieldId:
          type: string
          description: ID or alias of the field to sort by
          example: F693ab1c96f11ea3f4175e710
          minLength: 1
        direction:
          type: string
          description: Sort direction (asc or desc). Defaults to asc if omitted.
          enum:
          - asc
          - desc
          example: asc
      required:
      - fieldId
    FilterNodeDto:
      description: 'A node in the filter tree: either a leaf condition or a nested group'
      oneOf:
      - $ref: '#/components/schemas/FilterConditionDto'
      - $ref: '#/components/schemas/FilterGroupDto'