# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for SafeBase API documentation Documents API
  version: 1.0.0
extends: openapi/drata-documents-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 7
- target: $.paths['/document/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a trust center document
      effect: read
      questions:
      - How do I fetch a trust center document using my own external ID?
      - Can I look up a single document by its SafeBase ID?
      instructions:
      - text: Get document {id}.
        slots:
          id: path.id
      - text: Fetch the document whose external ID is {id}, using lookup type {type}.
        slots:
          id: path.id
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/document/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a trust center document
      effect: destructive
      questions:
      - What's the way to delete a document from our trust center library?
      - Can a document be removed permanently once it's outdated?
      instructions:
      - text: Delete document {id} from the trust center library.
        slots:
          id: path.id
      - text: Permanently remove the outdated trust center document {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/document/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a document's details
      effect: write
      questions:
      - How do I change when a trust center document expires?
      - Can I opt an existing document out of AI use?
      instructions:
      - text: Rename document {id} to {name}.
        slots:
          id: path.id
          name: requestBody.name
      - text: Set the expiration date of document {id} to {expiresAt}.
        slots:
          id: path.id
          expiresAt: requestBody.expiresAt
      - text: Attach tags {tagIds} to document {id}.
        slots:
          id: path.id
          tagIds: requestBody.tagIds
      method: generated
      generated: '2026-10-02'
- target: $.paths['/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List trust center documents
      effect: read
      questions:
      - Which documents are in my trust center library?
      - Can I filter the document list by tag or product?
      instructions:
      - text: List documents matching {query}.
        slots:
          query: query.query
      - text: List documents tagged {tags} for products {productIds}.
        slots:
          tags: query.tags
          productIds: query.productIds
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documents/upload'].put
  update:
    x-apievangelist-phrasing:
      intent: Create a document from an uploaded file
      effect: write
      questions:
      - How do I create a document after the file has been uploaded?
      - Can I swap in a new file behind an existing document?
      instructions:
      - text: Create document {name} from uploaded file {fileId} with mime type {mimeType}.
        slots:
          name: requestBody.name
          fileId: requestBody.fileId
          mimeType: requestBody.mimeType
      - text: Replace the file of document {replacementDocumentId} with upload {fileId} ({mimeType}), named {name}.
        slots:
          replacementDocumentId: requestBody.replacementDocumentId
          fileId: requestBody.fileId
          mimeType: requestBody.mimeType
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documents/upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Request a presigned document upload URL
      effect: write
      questions:
      - Where do I get a presigned URL to upload a document file?
      - What checksum and size details does the upload request need?
      instructions:
      - text: Request an upload URL for {fileName} ({mimeType}, {fileSize} bytes, MD5 {md5b64}).
        slots:
          fileName: requestBody.fileName
          mimeType: requestBody.mimeType
          fileSize: requestBody.fileSize
          md5b64: requestBody.md5b64
      - text: Get a presigned link so I can upload {fileName}, type {mimeType}, size {fileSize}, hash {md5b64}.
        slots:
          fileName: requestBody.fileName
          mimeType: requestBody.mimeType
          fileSize: requestBody.fileSize
          md5b64: requestBody.md5b64
      method: generated
      generated: '2026-09-26'
- target: $.paths['/document-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List allowed document types
      effect: read
      questions:
      - What document types can I assign to a document?
      - Which type values are valid when creating a document?
      instructions:
      - text: List the allowed document types.
      - text: Show me every document type I can pick from.
      method: generated
      generated: '2026-09-26'