API Evangelist conversational phrasing for External Documents API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for External Documents API
  version: 1.0.0
extends: openapi/profound-documents-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: 6
- target: $.paths['/v1/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List the organization's documents
      effect: read
      questions:
      - Which Profound documents can my organization see, most recently edited first?
      - Can I search my documents by text?
      - Why doesn't the document list give me a total count?
      instructions:
      - text: List documents in organization {organization_id}.
        slots:
          organization_id: query.organization_id
      - text: Find documents matching {q} in organization {organization_id}.
        slots:
          q: query.q
          organization_id: query.organization_id
      - text: Get the next {limit} documents in org {organization_id} after cursor {next_cursor}.
        slots:
          limit: query.limit
          organization_id: query.organization_id
          next_cursor: query.next_cursor
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a markdown document
      effect: write
      questions:
      - How do I create a new document from markdown?
      - What happens if I send a create request with a document id that already exists?
      instructions:
      - text: 'Create document {id} named {name} in org {organization_id} with this markdown: {content_markdown}'
        slots:
          id: requestBody.id
          name: requestBody.name
          organization_id: requestBody.organization_id
          content_markdown: requestBody.content_markdown
      - text: Make a new doc titled {name} for organization {organization_id} using id {id} and body {content_markdown}.
        slots:
          id: requestBody.id
          name: requestBody.name
          organization_id: requestBody.organization_id
          content_markdown: requestBody.content_markdown
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/documents/{document_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Read a document with tabs and comments
      effect: read
      questions:
      - Can I read the full text and comments of a document?
      - Why is the document body truncated, and how do I get the version hash?
      instructions:
      - text: Read document {document_id} in org {organization_id}.
        slots:
          document_id: path.document_id
          organization_id: query.organization_id
      - text: Open document {document_id} for org {organization_id} without preview, including comments {include_comments}.
        slots:
          document_id: path.document_id
          organization_id: query.organization_id
          include_comments: query.include_comments
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/documents/{document_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a document created via the API
      effect: destructive
      questions:
      - Can I delete a document that was created through the API?
      - Is a deleted document recoverable, and can I delete ones made in the app?
      instructions:
      - text: Delete document {document_id} from organization {organization_id}.
        slots:
          document_id: path.document_id
          organization_id: query.organization_id
      - text: Remove the API-created document {document_id} in org {organization_id} permanently.
        slots:
          document_id: path.document_id
          organization_id: query.organization_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/documents/{document_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Rename a document or change its visibility
      effect: write
      questions:
      - How do I rename a document?
      - Can I change who is able to see a document, and who is allowed to do that?
      instructions:
      - text: Rename document {document_id} in org {organization_id} to {name}.
        slots:
          document_id: path.document_id
          organization_id: requestBody.organization_id
          name: requestBody.name
      - text: Set visibility of document {document_id} in org {organization_id} to {visibility}.
        slots:
          document_id: path.document_id
          organization_id: requestBody.organization_id
          visibility: requestBody.visibility
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/documents/{document_id}/content'].post
  update:
    x-apievangelist-phrasing:
      intent: Overwrite a document's entire body
      effect: destructive
      questions:
      - How do I replace all the text in a document with new markdown?
      - Will overwriting a document's content wipe its other tabs and comment threads?
      instructions:
      - text: Overwrite the body of document {document_id} in org {organization_id} with {content_markdown}.
        slots:
          document_id: path.document_id
          organization_id: requestBody.organization_id
          content_markdown: requestBody.content_markdown
      - text: Replace document {document_id}'s content in org {organization_id} with {content_markdown} and keep the title (skip_title_sync {skip_title_sync}).
        slots:
          document_id: path.document_id
          organization_id: requestBody.organization_id
          content_markdown: requestBody.content_markdown
          skip_title_sync: requestBody.skip_title_sync
      method: generated
      generated: '2026-10-01'