# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for act.web.api Metadata Info API
  version: 1.0.0
extends: openapi/act-metadatainfo-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['/api/metadata/drop-down/lists/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a drop-down list
      effect: read
      questions:
      - What values are in one particular drop-down list?
      - Can I look up a drop-down list's settings by its id?
      instructions:
      - text: Get drop-down list {id}.
        slots:
          id: path.id
      - text: Show the definition and items of drop-down list {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/drop-down/lists/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a drop-down list
      effect: write
      questions:
      - Can I rename a drop-down list or change its items?
      - Is it possible to stop users editing a drop-down list?
      instructions:
      - text: Rename drop-down list {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Replace the items in drop-down list {id} with {items}.
        slots:
          id: path.id
          items: requestBody.items
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/drop-down/lists/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a drop-down list
      effect: destructive
      questions:
      - Can I remove a drop-down list I no longer use?
      - What happens if I delete a drop-down list definition?
      instructions:
      - text: Delete drop-down list {id}.
        slots:
          id: path.id
      - text: Remove the drop-down list {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/{recordType}/fields/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a field definition for a record type
      effect: read
      questions:
      - What are the settings of one field on contacts or opportunities?
      - Can I see a field's data type and length on a given record type?
      instructions:
      - text: Get field {id} on record type {recordType}.
        slots:
          id: path.id
          recordType: path.recordType
      - text: Show the definition of {recordType} field {id}.
        slots:
          recordType: path.recordType
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/{recordType}/fields/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a field definition
      effect: write
      questions:
      - Can I change a custom field's display name or default value?
      - Is it possible to make an existing field required or read-only?
      instructions:
      - text: Rename {recordType} field {id} to display as {displayName}.
        slots:
          recordType: path.recordType
          id: path.id
          displayName: requestBody.displayName
      - text: Set the default value of {recordType} field {id} to {defaultValue}.
        slots:
          recordType: path.recordType
          id: path.id
          defaultValue: requestBody.defaultValue
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/{recordType}/fields/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a field
      effect: destructive
      questions:
      - Can I remove a custom field from a record type?
      - What happens to data when I delete a field definition?
      instructions:
      - text: Delete field {id} from record type {recordType}.
        slots:
          id: path.id
          recordType: path.recordType
      - text: Remove the {recordType} field {id}.
        slots:
          recordType: path.recordType
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/datatypes'].get
  update:
    x-apievangelist-phrasing:
      intent: List allowed field data types
      effect: read
      questions:
      - Which data types can a new field use in Act!?
      - What field types are allowed for opportunities versus contacts?
      instructions:
      - text: List the allowed field data types.
      - text: Show which data types a {recordType} field can use.
        slots:
          recordType: query.recordType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/drop-down/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List all drop-down lists
      effect: read
      questions:
      - What drop-down lists are defined in my database?
      - Can I filter drop-down lists with an OData query?
      instructions:
      - text: List all drop-down lists.
      - text: Show every drop-down list definition in the database.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/drop-down/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a drop-down list
      effect: write
      questions:
      - How do I set up a new drop-down list for a field?
      - Can I create a drop-down list with its items in one call?
      instructions:
      - text: Create a drop-down list called {name} of type {type}.
        slots:
          name: requestBody.name
          type: requestBody.type
      - text: Add a {type} drop-down list named {name} with items {items}.
        slots:
          type: requestBody.type
          name: requestBody.name
          items: requestBody.items
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/drop-down/lists/{list}/items/{item}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one item in a drop-down list
      effect: read
      questions:
      - Can I look up a single entry inside a drop-down list?
      - What does one pick list item contain?
      instructions:
      - text: Get item {item} from drop-down list {list}.
        slots:
          item: path.item
          list: path.list
      - text: Show pick list entry {item} of list {list}.
        slots:
          item: path.item
          list: path.list
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/drop-down/lists/{list}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List the items in a drop-down list
      effect: read
      questions:
      - Which choices does a given drop-down list offer?
      - Can I get every pick list entry for one list?
      instructions:
      - text: List the items in drop-down list {list}.
        slots:
          list: path.list
      - text: Show all choices offered by drop-down list {list}.
        slots:
          list: path.list
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/entities'].get
  update:
    x-apievangelist-phrasing:
      intent: List record types and custom tables
      effect: read
      questions:
      - What entities, including custom tables, exist in my database?
      - Can I see all record types the API exposes?
      instructions:
      - text: List all entities in the database.
      - text: Show every record type and custom table.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/entities'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom table
      effect: write
      questions:
      - How do I add my own custom table to the database?
      - Can a new custom table be linked to contacts or companies as a parent?
      instructions:
      - text: Create a custom table named {name} displayed as {displayName}.
        slots:
          name: requestBody.name
          displayName: requestBody.displayName
      - text: Create custom table {name} labeled {displayName} and link it to {parentEntities}.
        slots:
          name: requestBody.name
          displayName: requestBody.displayName
          parentEntities: requestBody.parentEntities
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List fields across all record types
      effect: read
      questions:
      - What fields exist across the whole database?
      - Can I list only customizable fields, or every visible one?
      instructions:
      - text: List all fields across every record type.
      - text: Show database-wide fields with show-all set to {showAll}.
        slots:
          showAll: query.showAll
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/fields/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a field by id alone
      effect: read
      questions:
      - Can I look up a field just by its id without knowing the record type?
      - Which record type does a given field id belong to?
      instructions:
      - text: Get field {id} without specifying a record type.
        slots:
          id: path.id
      - text: Look up field definition {id} by id only.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/{recordType}/fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List fields on a record type
      effect: read
      questions:
      - What fields are on contacts, companies or opportunities?
      - Can I list just the customizable fields for one record type?
      instructions:
      - text: List the fields on record type {recordType}.
        slots:
          recordType: path.recordType
      - text: Show {recordType} fields with show-all set to {showAll}.
        slots:
          recordType: path.recordType
          showAll: query.showAll
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/{recordType}/fields'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom field
      effect: write
      questions:
      - How do I add a new custom field to contacts?
      - Can I make a new field tracked or attach a drop-down to it?
      instructions:
      - text: Create a {type} field named {name} on {recordType}.
        slots:
          type: requestBody.type
          name: requestBody.name
          recordType: path.recordType
      - text: Add field {name} of type {type} to {recordType} with default {defaultValue}.
        slots:
          name: requestBody.name
          type: requestBody.type
          recordType: path.recordType
          defaultValue: requestBody.defaultValue
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/{recordType}/picklists/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a pick list for a record type
      effect: read
      questions:
      - What's in a specific pick list attached to a record type?
      - Can I fetch one pick list by id for contacts or opportunities?
      instructions:
      - text: Get pick list {id} for {recordType}.
        slots:
          id: path.id
          recordType: path.recordType
      - text: Show {recordType} pick list {id} with show-all {showAll}.
        slots:
          recordType: path.recordType
          id: path.id
          showAll: query.showAll
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/{recordType}/picklists'].get
  update:
    x-apievangelist-phrasing:
      intent: List pick lists for a record type
      effect: read
      questions:
      - Which pick lists are used on a record type?
      - Can I list every pick list for opportunities?
      instructions:
      - text: List the pick lists for {recordType}.
        slots:
          recordType: path.recordType
      - text: Show all {recordType} pick lists with show-all {showAll}.
        slots:
          recordType: path.recordType
          showAll: query.showAll
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/metadata/entities/{recordType}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom table
      effect: destructive
      questions:
      - Can I drop a custom table along with its parent links?
      - What gets removed when I delete a custom entity?
      instructions:
      - text: Delete custom table {recordType}.
        slots:
          recordType: path.recordType
      - text: Drop custom entity {recordType} and its parent-link junction tables.
        slots:
          recordType: path.recordType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/cache-refresh'].get
  update:
    x-apievangelist-phrasing:
      intent: Refresh the metadata cache with a GET
      effect: write
      questions:
      - Can I trigger a metadata cache refresh with a simple GET request?
      - Is there a GET endpoint that reloads field and table metadata?
      instructions:
      - text: Refresh the metadata cache using the GET endpoint.
      - text: Reload cached metadata via GET.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/cache-refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh the metadata cache with a POST
      effect: write
      questions:
      - Is there a POST endpoint to force a metadata cache refresh?
      - My new custom field isn't showing up; which POST call reloads the metadata?
      instructions:
      - text: Refresh the metadata cache using the POST endpoint.
      - text: Post a metadata cache refresh after my schema change.
      method: generated
      generated: '2026-10-01'