# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Knowledge Custom Instructions API
  version: 1.0.0
extends: openapi/ada-custominstructions-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 5
- target: $.paths['/v2/custom-instructions/'].get
  update:
    x-apievangelist-phrasing:
      intent: List the AI Agent's custom instructions
      effect: read
      questions:
      - What custom instructions is my AI Agent following right now?
      - Can I see inactive custom instructions alongside the live ones?
      instructions:
      - text: List all my custom instructions.
      - text: Show the next {limit} custom instructions after cursor {cursor}.
        slots:
          limit: query.limit
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/custom-instructions/'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a custom instruction
      effect: write
      questions:
      - How do I give my Ada AI Agent a new rule to follow?
      - Are newly added custom instructions active immediately or off by default?
      - Can I limit when a custom instruction applies using a variable-based rule?
      instructions:
      - text: Create a custom instruction titled {title} that says {text}.
        slots:
          title: requestBody.title
          text: requestBody.text
      - text: Add an enabled custom instruction {title} with text {text}, enabled set to {enabled}.
        slots:
          title: requestBody.title
          text: requestBody.text
          enabled: requestBody.enabled
      - text: Create instruction {title} saying {text} that only applies when {availability_rules}.
        slots:
          title: requestBody.title
          text: requestBody.text
          availability_rules: requestBody.availability_rules
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/custom-instructions/{custom_instruction_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Look up one custom instruction
      effect: read
      questions:
      - How can I view the full text and notes of one custom instruction?
      - Is a particular custom instruction currently enabled?
      instructions:
      - text: Get custom instruction {custom_instruction_id}.
        slots:
          custom_instruction_id: path.custom_instruction_id
      - text: Show me the rule text of custom instruction {custom_instruction_id}.
        slots:
          custom_instruction_id: path.custom_instruction_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/custom-instructions/{custom_instruction_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom instruction
      effect: destructive
      questions:
      - How do I permanently remove a custom instruction from my AI Agent?
      - Can I delete a custom instruction instead of just disabling it?
      instructions:
      - text: Delete custom instruction {custom_instruction_id}.
        slots:
          custom_instruction_id: path.custom_instruction_id
      - text: Remove custom instruction {custom_instruction_id} entirely.
        slots:
          custom_instruction_id: path.custom_instruction_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/custom-instructions/{custom_instruction_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Edit or toggle a custom instruction
      effect: write
      questions:
      - How do I turn an existing custom instruction on or off?
      - Can I change an instruction's wording without touching its other fields?
      - Which way do I clear the availability rule on an instruction I already created?
      instructions:
      - text: Set enabled to {enabled} on custom instruction {custom_instruction_id}.
        slots:
          enabled: requestBody.enabled
          custom_instruction_id: path.custom_instruction_id
      - text: Change the text of custom instruction {custom_instruction_id} to {text}.
        slots:
          custom_instruction_id: path.custom_instruction_id
          text: requestBody.text
      - text: Rename custom instruction {custom_instruction_id} to {title} and update its notes to {notes}.
        slots:
          custom_instruction_id: path.custom_instruction_id
          title: requestBody.title
          notes: requestBody.notes
      method: generated
      generated: '2026-09-26'