# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Archbee Public Documents API
  version: 1.0.0
extends: openapi/archbee-documents-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['/doc'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a document's content
      effect: read
      questions:
      - How do I fetch the contents of a single Archbee doc by its id?
      - Can I get a document back as HTML or JSON instead of markdown?
      instructions:
      - text: Get document {docId} as markdown.
        slots:
          docId: requestBody.docId
      - text: Fetch doc {docId} in {format} format.
        slots:
          docId: requestBody.docId
          format: requestBody.format
      method: generated
      generated: '2026-09-26'
- target: $.paths['/doc'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a document
      effect: write
      questions:
      - How do I write new markdown content into a doc, creating it if it doesn't exist yet?
      - Can I change a document's title, slug or hidden flag while updating its content?
      - Is MDX with components like hints and tabs accepted when saving a doc?
      instructions:
      - text: 'Update document {docId} with this content: {content}'
        slots:
          docId: requestBody.docId
          content: requestBody.content
      - text: Create a new doc titled {title} with content {content}.
        slots:
          title: requestBody.title
          content: requestBody.content
      - text: Move doc {docId} under parent {parentDocId} and replace its body with {content}.
        slots:
          docId: requestBody.docId
          parentDocId: requestBody.parentDocId
          content: requestBody.content
      method: generated
      generated: '2026-09-26'
- target: $.paths['/doc'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a document
      effect: destructive
      questions:
      - How do I permanently remove a doc from my documentation?
      - Is deleting a document reversible, or is it gone for good?
      instructions:
      - text: Delete document {docId}.
        slots:
          docId: requestBody.docId
      - text: Permanently remove doc {docId} from the space.
        slots:
          docId: requestBody.docId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/docs/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search documents or ask the docs AI
      effect: read
      questions:
      - How can I search across my docs by keyword or title?
      - Can I get an AI-generated answer from my documentation along with the source docs?
      - Which docs are children of a given parent document?
      instructions:
      - text: Search my docs for {query}.
        slots:
          query: requestBody.query
      - text: 'Ask the docs AI: {query}'
        slots:
          query: requestBody.query
      - text: Find docs whose title matches {query}.
        slots:
          query: requestBody.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/import-content'].post
  update:
    x-apievangelist-phrasing:
      intent: Import markdown files as new docs
      effect: write
      questions:
      - How do I import an existing markdown file as a new doc?
      - Can I upload a zip of markdown files and keep the folder structure as a doc tree?
      instructions:
      - text: Import {file} as a new document.
        slots:
          file: requestBody.file
      - text: Import the zipped markdown archive {file} into a new doc tree.
        slots:
          file: requestBody.file
      method: generated
      generated: '2026-09-26'