openapi: 3.2.0
info:
  title: Workfront Workspaces API
  version: '1.0'
  description: 'Operations tagged Workspaces across 2 of this provider''s published API definitions: workfront-planning-v1-openapi.json, workfront-planning-v2-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{customer-domain}/maestro/api
  description: Workfront Planning Service Url
tags:
- name: Workspaces
  description: Workspace Controller
paths:
  /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'
    servers:
    - url: https://{customer-domain}/maestro/api
      description: Workfront Planning Service Url
  /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'
    servers:
    - url: https://{customer-domain}/maestro/api
      description: Workfront Planning Service Url
  /v2/workspaces/{id}:
    get:
      tags:
      - Workspaces
      summary: Get Workspace
      description: Retrieve a workspace by its ID.
      operationId: getWorkspace
      parameters:
      - name: id
        in: path
        description: ID of the workspace to be retrieved
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceBaseDto'
        '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:
      - Workspaces
      summary: Update Workspace
      description: Update an existing workspace using PUT (full replacement). All fields not provided in the request will be set to null.
      operationId: updateWorkspace
      parameters:
      - name: id
        in: path
        description: ID of the workspace to be updated
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceBaseDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceBaseDto'
        '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:
      - Workspaces
      summary: Delete Workspace
      description: Delete a workspace by its ID.
      operationId: deleteWorkspace
      parameters:
      - name: id
        in: path
        description: ID of the workspace 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:
      - Workspaces
      summary: Patch Workspace
      description: Partially update a workspace using PATCH (merge-patch semantics). Only provided fields will be updated; omitted fields remain unchanged.
      operationId: patchWorkspace
      parameters:
      - name: id
        in: path
        description: ID of the workspace to be patched
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceBaseDto'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceBaseDto'
        '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'
    servers:
    - url: https://{customer-domain}/maestro/api
      description: Workfront Planning Service Url
  /v2/workspaces:
    get:
      tags:
      - Workspaces
      summary: Get All Workspaces
      description: Retrieve a cursor-paginated list of all workspaces.
      operationId: getWorkspaces
      parameters:
      - 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-50, default 20)
        required: false
        schema:
          type: integer
          format: int32
          default: 20
          maximum: 50
          minimum: 1
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CursorResponseWorkspaceDto'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
    post:
      tags:
      - Workspaces
      summary: Create Workspace
      description: Create a new workspace.
      operationId: createWorkspace
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkspaceBaseDto'
        required: true
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceBaseDto'
        '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 (admin only, or WORKSPACE_LIMIT_EXCEEDED)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2ProblemDetail'
    servers:
    - url: https://{customer-domain}/maestro/api
      description: Workfront Planning Service Url
components:
  schemas:
    FieldLookupOptionsDto:
      type: object
      properties:
        referenceFieldId:
          type: string
        rollup:
          type: string
        sourceField:
          $ref: '#/components/schemas/FieldDto'
    RecordTypeSectionDto:
      type: object
      properties:
        name:
          type: string
        displayName:
          type: string
        recordTypeIds:
          type: array
          items:
            type: string
    FieldFormulaOptionsDto:
      type: object
      properties:
        formula:
          type: string
    WorkspaceListDto:
      type: object
      properties:
        workspaces:
          type: array
          items:
            $ref: '#/components/schemas/WorkspaceDto'
        permission:
          type: string
          enum:
          - manage
          - edit
          - view
          - none
    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'
    FieldDateOptionsDto:
      type: object
      properties:
        dateFormat:
          type: string
          enum:
          - locale
          - standard
          - friendly
          - european
          - iso
        timeFormat:
          type: string
          enum:
          - h12
          - h24
    FieldReferenceExternalOptionsDto:
      type: object
      properties:
        connectionName:
          type: string
        objectName:
          type: string
        connectionOptions:
          type: object
          additionalProperties:
            type: string
    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
    FieldUserOptionsDto:
      type: object
      properties:
        multipleUsersAllowed:
          type: boolean
    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
    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'
    FieldReferenceLookupFieldDto:
      type: object
      properties:
        fieldId:
          type: string
        rollup:
          type: string
    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
    FieldOptionDto:
      type: object
      properties:
        name:
          type: string
        displayName:
          type: string
        color:
          type: string
    RecordTypeSectionDto_2:
      type: object
      description: Section for organizing and grouping record types within a workspace. Sections are ordered by their position in the array.
      properties:
        displayName:
          type: string
          description: Display name of the record type section
          example: Marketing
          maxLength: 256
          minLength: 0
        recordTypeIds:
          type: array
          description: List of record type IDs included in this section
          items:
            type: string
      required:
      - displayName
    CursorResponseWorkspaceDto:
      type: object
      description: Cursor-paginated list of workspaces
      properties:
        content:
          type: array
          description: List of workspaces in the current page
          items:
            $ref: '#/components/schemas/WorkspaceBaseDto'
        cursor:
          $ref: '#/components/schemas/CursorInfo'
          description: Cursor metadata for fetching subsequent pages
    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
    WorkspaceBaseDto:
      type: object
      description: Base class for Workspace DTOs containing common workspace properties
      properties:
        id:
          type: string
          description: Unique identifier of the entity
          example: Ws69a976d02587b929c9e26dfa
          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 workspace
          example: marketing-workspace
          readOnly: true
        name:
          type: string
          description: Display name of the workspace. Maximum 256 characters; cannot be blank.
          example: Marketing Workspace
          maxLength: 256
          minLength: 0
          pattern: (?s)^\s*\S.*$
        description:
          type: string
          description: Description of the workspace purpose and content. Maximum 1024 characters.
          example: Workspace for managing marketing campaigns and assets
          maxLength: 1024
          minLength: 0
        color:
          type: string
          description: Color theme for the workspace
          example: blue
        icon:
          type: string
          description: Icon identifier for the workspace
          example: briefcase
        ownerId:
          type: string
          description: User ID of the workspace owner
          example: 1C341E7B682505430A494138@0bd0200063c87f9749412b.e
        recordTypeSections:
          type: array
          description: List of record type sections for organizing record types
          items:
            $ref: '#/components/schemas/RecordTypeSectionDto_2'
    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
    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
    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
x-refined-from:
- workfront-planning-v1-openapi.json
- workfront-planning-v2-openapi.json