# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for X-Author Document API
  version: 1.0.0
extends: openapi/conga-document-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: 13
- target: $.paths['/api/xauthor/v1/documents/content/convert/opcxml-to-html'].post
  update:
    x-apievangelist-phrasing:
      intent: Convert OPC XML document content to HTML
      effect: read
      questions:
      - How do I turn Word OPC XML content into HTML with Conga X-Author?
      - Can I render flat OPC XML from a document as HTML?
      instructions:
      - text: Convert this OPC XML content {opcXMLContent} to HTML for org type {OrgType}.
        slots:
          opcXMLContent: requestBody.opcXMLContent
          OrgType: header.OrgType
      - text: Give me the HTML version of the OPC XML {opcXMLContent}.
        slots:
          opcXMLContent: requestBody.opcXMLContent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/content/no-datepicker'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace Word content controls with plain text
      effect: write
      questions:
      - Why do date pickers and drop-downs break in Word online, and can I flatten them?
      - Can I strip structured document tags from a checked-out document and keep their text?
      instructions:
      - text: Convert the date pickers and drop-down controls in the checked-out document to plain text for org type {OrgType}.
        slots:
          OrgType: header.OrgType
      - text: Remove SDT content controls from my document so it opens cleanly in Word online.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/metadata'].post
  update:
    x-apievangelist-phrasing:
      intent: Read agreement details from a document file
      effect: read
      questions:
      - Can I find out which agreement a Word file belongs to by uploading it?
      - What agreement details are embedded in a document file?
      instructions:
      - text: Read the agreement details embedded in document file {documentFile} for org type {OrgType}.
        slots:
          documentFile: requestBody.documentFile
          OrgType: header.OrgType
      - text: Identify the agreement behind the file {documentFile}.
        slots:
          documentFile: requestBody.documentFile
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/suggested-filename'].post
  update:
    x-apievangelist-phrasing:
      intent: Get a suggested file name for a document
      effect: read
      questions:
      - What file name should a generated agreement document get?
      - Can I get a version-aware file name suggestion for an agreement attachment?
      instructions:
      - text: Suggest a file name for attachment {attachmentId} on agreement {agreementId} ({OrgType} org).
        slots:
          attachmentId: requestBody.attachmentId
          agreementId: requestBody.agreementId
          OrgType: header.OrgType
      - text: Propose a {fileType} file name for agreement {agreementId} using template {templateId}.
        slots:
          fileType: requestBody.fileType
          agreementId: requestBody.agreementId
          templateId: requestBody.templateId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a document or attachment record
      effect: read
      questions:
      - How do I look up an attachment record by its ID in X-Author?
      - What information comes back for a document attachment?
      instructions:
      - text: Fetch the document attachment {attachmentId} for org type {OrgType}.
        slots:
          attachmentId: path.attachmentId
          OrgType: header.OrgType
      - text: Show the attachment record {attachmentId}.
        slots:
          attachmentId: path.attachmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}/clauses'].get
  update:
    x-apievangelist-phrasing:
      intent: List the clauses in a document
      effect: read
      questions:
      - Which clauses appear inside an agreement document?
      - Can I extract the list of clauses from an attachment?
      instructions:
      - text: List the clauses found in attachment {attachmentId} for org type {OrgType}.
        slots:
          attachmentId: path.attachmentId
          OrgType: header.OrgType
      - text: Show every clause inside document {attachmentId}.
        slots:
          attachmentId: path.attachmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}/content'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a document's content for Windows or Mac
      effect: read
      questions:
      - How do I download the file content of an attachment for the desktop add-in?
      - Can I get a document's content with its protection removed?
      instructions:
      - text: Download the content of attachment {attachmentId} for org type {OrgType}.
        slots:
          attachmentId: path.attachmentId
          OrgType: header.OrgType
      - text: Get document {attachmentId} content with remove-protection set to {isRemoveProtection}.
        slots:
          attachmentId: path.attachmentId
          isRemoveProtection: query.isRemoveProtection
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}/content-body'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a document's content as a string and bytes
      effect: read
      questions:
      - Can I get the body of a document both as text and as raw bytes?
      - Is there a way to update the document title while fetching its content body?
      instructions:
      - text: Fetch the content body of attachment {attachmentId} as string and bytes ({OrgType} org).
        slots:
          attachmentId: path.attachmentId
          OrgType: header.OrgType
      - text: Get the content body of {attachmentId} with update-title set to {updateDocumentTitle}.
        slots:
          attachmentId: path.attachmentId
          updateDocumentTitle: query.updateDocumentTitle
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}/content-body-metadata-extracted'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a document's content body with metadata extracted
      effect: read
      questions:
      - Can I fetch a document body with its embedded metadata already pulled out?
      - Which call returns content body plus extracted metadata for an attachment?
      instructions:
      - text: Get the metadata-extracted content body of attachment {attachmentId} for org type {OrgType}.
        slots:
          attachmentId: path.attachmentId
          OrgType: header.OrgType
      - text: Fetch {attachmentId} body with metadata separated out.
        slots:
          attachmentId: path.attachmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}/content-metadata'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a document's content metadata
      effect: read
      questions:
      - What content metadata is stored for an attachment?
      - Can I read only a document's content metadata without downloading the file?
      instructions:
      - text: Show the content metadata of attachment {attachmentId} for org type {OrgType}.
        slots:
          attachmentId: path.attachmentId
          OrgType: header.OrgType
      - text: Get just the metadata for document {attachmentId}.
        slots:
          attachmentId: path.attachmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}/content/onedrive-stream'].post
  update:
    x-apievangelist-phrasing:
      intent: Open a document in Word online via OneDrive
      effect: read
      questions:
      - How do I open an agreement attachment in Word online?
      - Can I stream a document to OneDrive using my access token?
      instructions:
      - text: Open attachment {attachmentId} in Word online as {documentName} for org type {OrgType}.
        slots:
          attachmentId: path.attachmentId
          documentName: requestBody.documentName
          OrgType: header.OrgType
      - text: Stream document {attachmentId} to OneDrive with access token {accessToken}.
        slots:
          attachmentId: path.attachmentId
          accessToken: requestBody.accessToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}/content/stream'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a document as a DOCX stream
      effect: read
      questions:
      - Can I download an attachment as a raw DOCX octet stream?
      - Which call returns the binary Word file for an attachment?
      instructions:
      - text: Stream attachment {attachmentId} as a DOCX file for org type {OrgType}.
        slots:
          attachmentId: path.attachmentId
          OrgType: header.OrgType
      - text: Download the binary Word file for {attachmentId}.
        slots:
          attachmentId: path.attachmentId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/xauthor/v1/documents/{attachmentId}/size'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an attachment's file size
      effect: read
      questions:
      - How large is an attachment file in megabytes?
      - Can I check a document's size before downloading it?
      instructions:
      - text: Get the file size in MB of attachment {attachmentId} for org type {OrgType}.
        slots:
          attachmentId: path.attachmentId
          OrgType: header.OrgType
      - text: Tell me how big document {attachmentId} is.
        slots:
          attachmentId: path.attachmentId
      method: generated
      generated: '2026-10-01'