openapi: 3.2.0
info:
  title: Workfront Planning Records 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. \n* **API paths**:\n  * Gateway URL: https://{customer-domain}.my.workfront.com\n  * Base path for this API: /maestro/api\n  * Example of a complete path for making a call: https://{customer-domain}.my.workfront.com/maestro/api/v1/records/{id}\n* **Required headers**:\n  * 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/)."
servers:
- url: https://{customer-domain}/maestro/api
  description: Workfront Planning Service Url
basePath: /maestro/api
tags:
- 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'
components:
  schemas:
    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
    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'
    RecordSorting:
      type: object
      properties:
        fieldId:
          type: string
        direction:
          type: string
          enum:
          - asc
          - desc
    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
    CoverImage:
      type: object
      properties:
        url:
          type: string
        position:
          type: integer
          format: int32
    JsonNode:
      type: object
    RecordGroupDto:
      type: object
      properties:
        fieldId:
          type: string
        value:
          type: object
        recordIds:
          type: array
          items:
            type: string
    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