# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for knowledge > articles API
  version: 1.0.0
extends: openapi/ada-knowledge-articles-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/knowledge/articles/'].get
  update:
    x-apievangelist-phrasing:
      intent: List knowledge articles
      effect: read
      questions:
      - Which knowledge articles does my AI Agent have?
      - Can I list only the disabled articles in a given language?
      - How do I see the articles that came from one knowledge source?
      instructions:
      - text: List knowledge articles tagged {tag_ids}.
        slots:
          tag_ids: query.tag_ids
      - text: Show articles from knowledge source {knowledge_source_id} in {language}.
        slots:
          knowledge_source_id: query.knowledge_source_id
          language: query.language
      - text: List articles where enabled is {enabled}, {limit} at a time.
        slots:
          enabled: query.enabled
          limit: query.limit
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/knowledge/articles/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete knowledge articles by filter
      effect: destructive
      questions:
      - How do I delete every article from one knowledge source at once?
      - Is bulk article deletion immediate or does it happen in the background?
      instructions:
      - text: Delete all articles in knowledge source {knowledge_source_id}.
        slots:
          knowledge_source_id: query.knowledge_source_id
      - text: Remove every article tagged {tag_ids} in {language}.
        slots:
          tag_ids: query.tag_ids
          language: query.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/knowledge/articles/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one knowledge article
      effect: read
      questions:
      - How do I read the content of a single knowledge article?
      - Can I fetch one article by id to check what the AI Agent knows?
      instructions:
      - text: Get knowledge article {id}.
        slots:
          id: path.id
      - text: Show me the full text of article {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/knowledge/articles/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one knowledge article
      effect: destructive
      questions:
      - How do I remove a single outdated article from the knowledge base?
      - Can I delete just one article by its id?
      instructions:
      - text: Delete knowledge article {id}.
        slots:
          id: path.id
      - text: Remove the single article {id} from the knowledge base.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/v2/knowledge/bulk/articles/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update knowledge articles in bulk
      effect: write
      questions:
      - How do I sync my help center articles into the AI Agent's knowledge base?
      - What's the maximum payload and article size for a bulk article upload?
      - Does uploading an article with an existing id overwrite it?
      instructions:
      - text: Upsert this batch of knowledge articles.
      - text: Sync my help center articles into the knowledge base, updating any that already exist.
      method: generated
      generated: '2026-09-26'