# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Workfront Records API
  version: 1.0.0
extends: openapi/workfront-records-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 22
- target: $.paths['/v1/records/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Fetch a record with the legacy v1 endpoint
      effect: read
      questions:
      - Can I still pull a single record through the older v1 records endpoint?
      - Is there a way to choose which attributes come back when I fetch a record on the v1 API?
      instructions:
      - text: Use the v1 endpoint to fetch record {id}.
        slots:
          id: path.id
      - text: Get record {id} from the legacy v1 API with only the attributes {attributes}.
        slots:
          id: path.id
          attributes: query.attributes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/records/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a record with the legacy v1 endpoint
      effect: write
      questions:
      - How would I change a record's field data using the original v1 records API?
      - Can the v1 API swap a record's cover image or thumbnail URL?
      instructions:
      - text: Through the legacy v1 API, update record {id} with field data {data}.
        slots:
          id: path.id
          data: requestBody.data
      - text: Set the thumbnail of record {id} to {thumbnailUrl} using the v1 update endpoint.
        slots:
          id: path.id
          thumbnailUrl: requestBody.thumbnailUrl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/records/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a record with the legacy v1 endpoint
      effect: destructive
      questions:
      - Does the older v1 records API let me delete a single record by its ID?
      - Which v1 endpoint removes one record from Workfront Planning?
      instructions:
      - text: Delete record {id} using the legacy v1 endpoint.
        slots:
          id: path.id
      - text: Remove record {id} through the v1 records API.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/records'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a record with the legacy v1 endpoint
      effect: write
      questions:
      - How did the v1 API create a record when the record type goes in the body rather than the path?
      - Can I create a record on the v1 API and pass its record type ID in the request body?
      instructions:
      - text: With the legacy v1 API, create a record of record type {recordTypeId} holding {data}.
        slots:
          recordTypeId: requestBody.recordTypeId
          data: requestBody.data
      - text: Add a v1 record under record type {recordTypeId}.
        slots:
          recordTypeId: requestBody.recordTypeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/records/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search records by field values via v1 query string
      effect: read
      questions:
      - Can I search records by field value with a plain GET on the older v1 search endpoint?
      - Does the v1 query-string record search support offset and limit paging?
      instructions:
      - text: Using the v1 GET search, find records of record type {recordTypeId} matching filters {filters}.
        slots:
          recordTypeId: query.recordTypeId
          filters: query.filters
      - text: Run a v1 GET record search on record type alias {recordTypeAlias}, returning {limit} results from offset {offset}.
        slots:
          recordTypeAlias: query.recordTypeAlias
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/records/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search records by field values via v1 POST body
      effect: read
      questions:
      - Can the v1 record search take its filters and sorting in a POST body instead of the URL?
      - Is there a v1 search that lets me sort records and group them by fields in the request body?
      instructions:
      - text: Post a v1 record search for record type {recordTypeId} with filters {filters} in the body.
        slots:
          recordTypeId: requestBody.recordTypeId
          filters: requestBody.filters
      - text: Do a v1 body-based record search on record type {recordTypeId}, sorted by {sorting}.
        slots:
          recordTypeId: requestBody.recordTypeId
          sorting: requestBody.sorting
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/records/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a record by ID
      effect: read
      questions:
      - How can I look up one Workfront Planning record and see its field data?
      - What comes back when I retrieve a single record by its ID on the current API?
      instructions:
      - text: Get record {id}.
        slots:
          id: path.id
      - text: Show me the field values stored on record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/records/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a record's contents in full
      effect: write
      questions:
      - What happens to fields I leave out when I fully replace a record?
      - How do I overwrite every field on a record in one request?
      instructions:
      - text: Fully replace record {id} with field data {data}, clearing anything not included.
        slots:
          id: path.id
          data: requestBody.data
      - text: Overwrite record {id} entirely, setting its cover image to {coverImage}.
        slots:
          id: path.id
          coverImage: requestBody.coverImage
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/records/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a record
      effect: destructive
      questions:
      - How do I delete one record from a record type?
      - Can I remove a single Planning record by its ID?
      instructions:
      - text: Delete record {id}.
        slots:
          id: path.id
      - text: Permanently remove the record with ID {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/records/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change only some fields on a record
      effect: write
      questions:
      - Can I change just one field on a record without touching the others?
      - How do I clear a single field value on a record by sending null?
      instructions:
      - text: 'Patch record {id} so only these fields change: {data}.'
        slots:
          id: path.id
          data: requestBody.data
      - text: On record {id}, update just the thumbnail URL to {thumbnailUrl} and leave everything else alone.
        slots:
          id: path.id
          thumbnailUrl: requestBody.thumbnailUrl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records/bulk'].put
  update:
    x-apievangelist-phrasing:
      intent: Fully replace up to 100 records at once
      effect: write
      questions:
      - Can I overwrite many records in a record type in one call, replacing all their fields?
      - What's the maximum number of records a bulk full-replacement update accepts?
      instructions:
      - text: Bulk replace records in record type {recordTypeId}, nulling any fields not supplied.
        slots:
          recordTypeId: path.recordTypeId
      - text: Run a full-replacement bulk update on record type {recordTypeId} and return field aliases as keys.
        slots:
          recordTypeId: path.recordTypeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records/bulk'].post
  update:
    x-apievangelist-phrasing:
      intent: Create up to 100 records in one request
      effect: write
      questions:
      - How do I import a batch of new records into a record type at once?
      - How many records can I create in a single bulk create request?
      instructions:
      - text: Bulk create a batch of new records in record type {recordTypeId}.
        slots:
          recordTypeId: path.recordTypeId
      - text: Add these up-to-100 new records to record type {recordTypeId} in one request.
        slots:
          recordTypeId: path.recordTypeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records/bulk'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete up to 100 records at once
      effect: destructive
      questions:
      - Can I delete a list of records from a record type in a single call?
      - Is there a cap on how many record IDs a bulk delete takes?
      instructions:
      - text: Bulk delete records {ids} from record type {recordTypeId}.
        slots:
          ids: requestBody.ids
          recordTypeId: path.recordTypeId
      - text: 'Wipe out these record IDs in one go from record type {recordTypeId}: {ids}.'
        slots:
          recordTypeId: path.recordTypeId
          ids: requestBody.ids
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records/bulk'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update up to 100 records at once
      effect: write
      questions:
      - Can I change a few fields across many records without overwriting the rest?
      - Does a bulk merge-patch leave omitted fields on each record unchanged?
      instructions:
      - text: Bulk patch records in record type {recordTypeId}, changing only the fields I provide per record.
        slots:
          recordTypeId: path.recordTypeId
      - text: Apply partial edits to a batch of records in record type {recordTypeId} using field aliases.
        slots:
          recordTypeId: path.recordTypeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/records/{id}/thumbnail'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a thumbnail image for a record
      effect: write
      questions:
      - How do I attach a thumbnail picture to a record?
      - Which image formats can I upload as a record thumbnail?
      instructions:
      - text: Upload {file} as the thumbnail for record {id}.
        slots:
          file: requestBody.file
          id: path.id
      - text: Replace the thumbnail image on record {id} with the PNG {file}.
        slots:
          id: path.id
          file: requestBody.file
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/records/{id}/thumbnail'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a record's thumbnail
      effect: destructive
      questions:
      - How do I take the thumbnail image off a record?
      - Will removing a thumbnail fail if the record doesn't have one?
      instructions:
      - text: Remove the thumbnail from record {id}.
        slots:
          id: path.id
      - text: Clear record {id}'s thumbnail image.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records'].get
  update:
    x-apievangelist-phrasing:
      intent: List records in a record type
      effect: read
      questions:
      - How do I page through every record in a record type?
      - What order are records listed in by default, and can I change the sort?
      instructions:
      - text: List the records in record type {recordTypeId}.
        slots:
          recordTypeId: path.recordTypeId
      - text: Show page {page} of record type {recordTypeId}'s records, {size} per page, sorted by {sort}.
        slots:
          page: query.page
          recordTypeId: path.recordTypeId
          size: query.size
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a record in a record type
      effect: write
      questions:
      - How do I add a new record to a record type?
      - Is there a limit on how many records one record type can hold?
      instructions:
      - text: Create a record in record type {recordTypeId} with field data {data}.
        slots:
          recordTypeId: path.recordTypeId
          data: requestBody.data
      - text: Add one new record to record type {recordTypeId}.
        slots:
          recordTypeId: path.recordTypeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records/search'].get
  update:
    x-apievangelist-phrasing:
      intent: Search a record type's records with URL filters
      effect: read
      questions:
      - Can I filter records in a record type by passing a JSON filter in the query string?
      - How do I limit a record search to certain workspaces for a global record type?
      instructions:
      - text: Search record type {recordTypeId} with the URL filter {filter}.
        slots:
          recordTypeId: path.recordTypeId
          filter: query.filter
      - text: Query-string search record type {recordTypeId} scoped to workspaces {scopeWorkspaceIds}, grouped by {groupingFieldIds}.
        slots:
          recordTypeId: path.recordTypeId
          scopeWorkspaceIds: query.scopeWorkspaceIds
          groupingFieldIds: query.groupingFieldIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search a record type's records with nested filters
      effect: read
      questions:
      - Can I search records with nested AND/OR conditions sent in a request body?
      - Which record search lets me post typed filter conditions plus sort and grouping settings?
      instructions:
      - text: 'Search record type {recordTypeId} with this nested AND/OR filter body: {filter}.'
        slots:
          recordTypeId: path.recordTypeId
          filter: requestBody.filter
      - text: Post a search on record type {recordTypeId}, grouping by {group} and returning only fields {fieldIds}.
        slots:
          recordTypeId: path.recordTypeId
          group: requestBody.group
          fieldIds: query.fieldIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/record-types/{recordTypeId}/records/move'].post
  update:
    x-apievangelist-phrasing:
      intent: Reorder records within a record type
      effect: write
      questions:
      - How do I change the position of rows in a record type?
      - If moving records fails partway, do some of them still get moved?
      instructions:
      - text: In record type {recordTypeId}, move records {recordIds} to sit right after record {putAfterRecordId}.
        slots:
          recordTypeId: path.recordTypeId
          recordIds: requestBody.recordIds
          putAfterRecordId: requestBody.putAfterRecordId
      - text: Reorder record type {recordTypeId} so records {recordIds} come just before {putBeforeRecordId}.
        slots:
          recordTypeId: path.recordTypeId
          recordIds: requestBody.recordIds
          putBeforeRecordId: requestBody.putBeforeRecordId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/records/{id}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: See a record's field change history
      effect: read
      questions:
      - Who changed which fields on a record, and when?
      - Can I page through the edit history of a record?
      instructions:
      - text: Show the field change history for record {id}.
        slots:
          id: path.id
      - text: Get the next {limit} change events for record {id} after cursor {cursor}.
        slots:
          limit: query.limit
          id: path.id
          cursor: query.cursor
      method: generated
      generated: '2026-10-01'