# 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 Notes API
  version: 1.0.0
extends: openapi/act-notes-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: 16
- target: $.paths['/api/notes/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a note
      effect: read
      questions:
      - How do I open a single note by its id?
      - Can I get a note's text back as plain text instead of rich text?
      instructions:
      - text: Fetch note {id}.
        slots:
          id: path.id
      - text: Show note {id} with its text in {format} format.
        slots:
          id: path.id
          format: query.format
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/notes/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a note
      effect: write
      questions:
      - How do I overwrite a whole note, including its links to contacts and companies?
      - Can I resend a full note to change its text and associations?
      instructions:
      - text: Replace note {id} with the text {noteText}.
        slots:
          id: path.id
          noteText: requestBody.noteText
      - text: Fully update note {id} so it is linked to contacts {contacts}.
        slots:
          id: path.id
          contacts: requestBody.contacts
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/notes/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a note
      effect: destructive
      questions:
      - How do I permanently delete a note everywhere it appears?
      - Can a deleted note be recovered?
      instructions:
      - text: Delete note {id}.
        slots:
          id: path.id
      - text: Remove note {id} from the database entirely.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/notes/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit part of a note
      effect: write
      questions:
      - Can I change a note's text without touching its note type?
      - What happens if I pass an invalid note type when editing a note?
      instructions:
      - text: Change the text of note {id} to {noteText}.
        slots:
          id: path.id
          noteText: requestBody.noteText
      - text: Set note {id} to note type {noteTypeID}.
        slots:
          id: path.id
          noteTypeID: requestBody.noteTypeID
      - text: 'Mark note {id} as private: {isPrivate}.'
        slots:
          id: path.id
          isPrivate: requestBody.isPrivate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{contactId}/notes/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact's note
      effect: destructive
      questions:
      - How do I delete a note through a specific contact's notes?
      - Can I remove a note that belongs to one contact?
      instructions:
      - text: Delete note {id} from contact {contactId}'s notes.
        slots:
          id: path.id
          contactId: path.contactId
      - text: Remove contact {contactId}'s note {id}.
        slots:
          contactId: path.contactId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/notes/{id}/contacts/{contactId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Attach a contact to a note
      effect: write
      questions:
      - How do I link an extra contact to an existing note?
      - Will adding a contact to a note duplicate it if it is already linked?
      instructions:
      - text: Attach contact {contactId} to note {id}.
        slots:
          contactId: path.contactId
          id: path.id
      - text: Add contact {contactId} to the people on note {id}.
        slots:
          contactId: path.contactId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/notes/{id}/contacts/{contactId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Detach a contact from a note (deprecated POST)
      effect: destructive
      questions:
      - Is there still a legacy POST route that detaches a contact from a note?
      - What replaced the deprecated POST endpoint for unlinking a note's contact?
      instructions:
      - text: Use the deprecated POST route to detach contact {contactId} from note {id}.
        slots:
          contactId: path.contactId
          id: path.id
      - text: Unlink contact {contactId} from note {id} via the old POST endpoint.
        slots:
          contactId: path.contactId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/notes/{id}/contacts/{contactId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Detach a contact from a note
      effect: destructive
      questions:
      - How do I unlink a contact from a note without deleting the note?
      - Can I take one person off a shared note?
      instructions:
      - text: Detach contact {contactId} from note {id}.
        slots:
          contactId: path.contactId
          id: path.id
      - text: Take contact {contactId} off note {id} but keep the note.
        slots:
          contactId: path.contactId
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List or search all notes
      effect: read
      questions:
      - What notes exist across the whole database?
      - Can I search every note with an OData filter?
      instructions:
      - text: List all notes in the database.
      - text: Search every note and return the text as {format}.
        slots:
          format: query.format
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/notes'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a note
      effect: write
      questions:
      - How do I write a new note and attach it to a contact or company?
      - What note type does a new note get if I don't choose one?
      instructions:
      - text: Create a note saying {noteText} on contacts {contacts}.
        slots:
          noteText: requestBody.noteText
          contacts: requestBody.contacts
      - text: Add a note {noteText} to opportunities {opportunities}.
        slots:
          noteText: requestBody.noteText
          opportunities: requestBody.opportunities
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/companies/{id}/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a company's notes
      effect: read
      questions:
      - What notes have been logged against a company?
      - Can I limit a company's notes to only those directly on the company?
      instructions:
      - text: Show the notes for company {id}.
        slots:
          id: path.id
      - text: List notes for company {id} filtered by association {showFor}.
        slots:
          id: path.id
          showFor: query.showFor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/contacts/{id}/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a contact's notes
      effect: read
      questions:
      - What notes are on a particular contact?
      - Which notes have I written about this person?
      instructions:
      - text: Show the notes for contact {id}.
        slots:
          id: path.id
      - text: List contact {id}'s notes as {format}.
        slots:
          id: path.id
          format: query.format
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/group/{id}/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a group's notes (deprecated route)
      effect: read
      questions:
      - Does the old singular group notes route still work?
      - What is the deprecated /group path for reading a group's notes?
      instructions:
      - text: Use the deprecated singular group route to list notes for group {id}.
        slots:
          id: path.id
      - text: Fetch group {id}'s notes through the legacy endpoint.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/groups/{id}/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a group's notes
      effect: read
      questions:
      - What notes are attached to a group?
      - Can I narrow a group's notes to one kind of association?
      instructions:
      - text: Show the notes for group {id}.
        slots:
          id: path.id
      - text: List notes for group {id} filtered by association {showFor}.
        slots:
          id: path.id
          showFor: query.showFor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunity/{id}/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a deal's notes (deprecated route)
      effect: read
      questions:
      - Is the singular /opportunity notes route still supported?
      - What is the legacy path for reading a deal's notes?
      instructions:
      - text: Use the deprecated singular opportunity route to list notes for deal {id}.
        slots:
          id: path.id
      - text: Fetch opportunity {id}'s notes through the legacy endpoint.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/opportunities/{id}/notes'].get
  update:
    x-apievangelist-phrasing:
      intent: List an opportunity's notes
      effect: read
      questions:
      - What notes have been recorded on a deal?
      - Which notes are attached to this opportunity?
      instructions:
      - text: Show the notes for opportunity {id}.
        slots:
          id: path.id
      - text: List deal {id}'s notes as {format}.
        slots:
          id: path.id
          format: query.format
      method: generated
      generated: '2026-10-01'