# 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 History API
  version: 1.0.0
extends: openapi/act-history-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: 13
- target: $.paths['/api/history/{id}/contacts/{contactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Attach a contact to a history item
      effect: write
      questions:
      - Can I link another contact to a logged history entry?
      - What's the way to add a person to an existing history record?
      instructions:
      - text: Attach contact {contactId} to history item {id}.
        slots:
          contactId: path.contactId
          id: path.id
      - text: Link contact {contactId} to the history entry {id} if it isn't already.
        slots:
          contactId: path.contactId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/history/{id}/contacts/{contactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Detach a contact from a history item
      effect: destructive
      questions:
      - Can I remove a contact from a history entry without deleting the history?
      - What unlinks a person from a logged history record?
      instructions:
      - text: Detach contact {contactId} from history item {id}.
        slots:
          contactId: path.contactId
          id: path.id
      - text: Remove contact {contactId} from the history entry {id}.
        slots:
          contactId: path.contactId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/activities/{id}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: List history for an activity
      effect: read
      questions:
      - What history was recorded against a particular activity?
      - Can I see the history items tied to one meeting or call?
      instructions:
      - text: List history for activity {id}.
        slots:
          id: path.id
      - text: Show the history items linked to activity {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{id}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: List history for a company
      effect: read
      questions:
      - What has happened with a particular company account?
      - Can I include history from the company's contacts too, or only the company itself?
      instructions:
      - text: List history for company {id}.
        slots:
          id: path.id
      - text: Show company {id}'s history filtered by association {showFor}.
        slots:
          id: path.id
          showFor: query.showFor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: List history for a contact
      effect: read
      questions:
      - What interactions have we logged with one contact?
      - Can I see a contact's full history timeline?
      instructions:
      - text: List history for contact {id}.
        slots:
          id: path.id
      - text: Show every history item logged for contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/groups/{id}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: List history for a group
      effect: read
      questions:
      - What history has been logged for a group?
      - Can I limit group history to group-only entries or member contacts?
      instructions:
      - text: List history for group {id}.
        slots:
          id: path.id
      - text: Show group {id}'s history filtered by association {showFor}.
        slots:
          id: path.id
          showFor: query.showFor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{id}/history'].get
  update:
    x-apievangelist-phrasing:
      intent: List history for an opportunity
      effect: read
      questions:
      - What has happened on a particular deal so far?
      - Can I see the logged history of one opportunity?
      instructions:
      - text: List history for opportunity {id}.
        slots:
          id: path.id
      - text: Show the history timeline of deal {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/History/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a history entry
      effect: read
      questions:
      - Can I open a single history record to read its details?
      - What does one history item contain?
      instructions:
      - text: Get history entry {id}.
        slots:
          id: path.id
      - text: Show the details of history record {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/History/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a history entry
      effect: write
      questions:
      - How do I overwrite a history record with a full set of new values?
      - Can I fully rewrite a history entry's regarding and details text?
      instructions:
      - text: Replace history {id} with regarding {regarding} and details {details}.
        slots:
          id: path.id
          regarding: requestBody.regarding
          details: requestBody.details
      - text: Do a full update of history {id}, setting start {startTime} and end {endTime}.
        slots:
          id: path.id
          startTime: requestBody.startTime
          endTime: requestBody.endTime
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/History/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a history entry
      effect: destructive
      questions:
      - Can I remove a history record that was logged by mistake?
      - Is deleting a history entry permanent?
      instructions:
      - text: Delete history entry {id}.
        slots:
          id: path.id
      - text: Remove history record {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/History/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change selected fields on a history entry
      effect: write
      questions:
      - Can I fix only the details text of a history item without resending everything?
      - Is there a partial update for history entries?
      instructions:
      - text: Change just the details of history {id} to {details}.
        slots:
          id: path.id
          details: requestBody.details
      - text: 'Patch history {id} to mark it private: {isPrivate}.'
        slots:
          id: path.id
          isPrivate: requestBody.isPrivate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/History'].get
  update:
    x-apievangelist-phrasing:
      intent: List all history items
      effect: read
      questions:
      - Can I search every history record with an OData filter?
      - What history has been logged across the whole database?
      instructions:
      - text: List all history items.
      - text: Show every history record in the database.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/History'].post
  update:
    x-apievangelist-phrasing:
      intent: Log a new history item
      effect: write
      questions:
      - How do I record a call or meeting outcome as history?
      - Can I log history and link it to contacts and opportunities at the same time?
      instructions:
      - text: Log a history item regarding {regarding} with details {details}.
        slots:
          regarding: requestBody.regarding
          details: requestBody.details
      - text: Record history of type {historyTypeID} for contacts {contacts}.
        slots:
          historyTypeID: requestBody.historyTypeID
          contacts: requestBody.contacts
      method: generated
      generated: '2026-10-01'