# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Dialogflow ES API (v2) Documents API
  version: 1.0.0
extends: openapi/google-dialogflow-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: 22
- target: $.paths['/v2/projects/{projectsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a document from a knowledge base
      effect: read
      questions:
      - How can I see the details of one document in a project-level Dialogflow knowledge base?
      - Can I check a knowledge document's MIME type and latest reload status?
      instructions:
      - text: Get document {document} from knowledge base {knowledge_base} in project {project}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Show the project-level knowledge document {document} stored in {knowledge_base}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a document from a knowledge base
      effect: destructive
      questions:
      - Can I remove an outdated FAQ document from a project-level knowledge base?
      - Is deleting a single knowledge document possible without touching the rest of the base?
      instructions:
      - text: Delete document {document} from knowledge base {knowledge_base} in project {project}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Remove project-level knowledge document {document} from base {knowledge_base}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a knowledge base document
      effect: write
      questions:
      - How do I rename a document in a project-level knowledge base?
      - Can I switch on automatic reloading for a knowledge document I already added?
      instructions:
      - text: Rename document {document} in knowledge base {knowledge_base} of project {project} to {display_name}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          display_name: requestBody.displayName
      - text: Turn auto-reload {enable_auto_reload} on for project-level document {document}.
        slots:
          enable_auto_reload: requestBody.enableAutoReload
          document: path.documentsId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}:reload'].post
  update:
    x-apievangelist-phrasing:
      intent: Reload a knowledge document from its source
      effect: write
      questions:
      - Can I make Dialogflow re-fetch a knowledge document after its source file changed?
      - Is it possible to reload a project-level knowledge document from a new Cloud Storage URI?
      instructions:
      - text: Reload document {document} in knowledge base {knowledge_base} of project {project}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Refresh project-level knowledge document {document} from content URI {content_uri}.
        slots:
          document: path.documentsId
          content_uri: requestBody.contentUri
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/knowledgeBases/{knowledgeBasesId}/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents in a knowledge base
      effect: read
      questions:
      - What documents are loaded into my project-level knowledge base?
      - Can I filter a knowledge base's document list, for example by state or type?
      instructions:
      - text: List all documents in knowledge base {knowledge_base} of project {project}.
        slots:
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Show project-level documents in {knowledge_base} matching filter {filter}.
        slots:
          knowledge_base: path.knowledgeBasesId
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/knowledgeBases/{knowledgeBasesId}/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a document to a knowledge base
      effect: write
      questions:
      - How do I add an FAQ page or article to a project-level knowledge base?
      - Can a new knowledge document be created from raw content rather than a URL?
      instructions:
      - text: Create document {display_name} in knowledge base {knowledge_base} of project {project} from {content_uri}.
        slots:
          display_name: requestBody.displayName
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          content_uri: requestBody.contentUri
      - text: Add a project-level knowledge document of type {knowledge_types} with MIME type {mime_type} to {knowledge_base}.
        slots:
          knowledge_types: requestBody.knowledgeTypes
          mime_type: requestBody.mimeType
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}:export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export a knowledge document to Cloud Storage
      effect: write
      questions:
      - Can I export a project-level knowledge document to a Cloud Storage bucket?
      - Does exporting a knowledge document include its full content or just metadata?
      instructions:
      - text: Export document {document} from knowledge base {knowledge_base} in project {project} to {gcs_destination}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          gcs_destination: requestBody.gcsDestination
      - text: Export the full content of project-level document {document} to bucket path {gcs_destination}.
        slots:
          document: path.documentsId
          gcs_destination: requestBody.gcsDestination
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/knowledgeBases/{knowledgeBasesId}/documents:import'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk-import documents into a knowledge base
      effect: write
      questions:
      - How can I bulk-import many files from Cloud Storage into a project-level knowledge base?
      - Can imported knowledge documents share a template for type and MIME settings?
      instructions:
      - text: Import documents from {gcs_source} into knowledge base {knowledge_base} of project {project}.
        slots:
          gcs_source: requestBody.gcsSource
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Bulk-load project-level knowledge files from {gcs_source} using document template {template}.
        slots:
          gcs_source: requestBody.gcsSource
          template: requestBody.documentTemplate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a document from a regional knowledge base
      effect: read
      questions:
      - Can I look up one document in a knowledge base hosted in a specific region?
      - What state is a regional knowledge document in right now?
      instructions:
      - text: Get regional document {document} from knowledge base {knowledge_base} in project {project}, location {location}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          location: path.locationsId
      - text: Show the {location} knowledge document {document} in {knowledge_base}.
        slots:
          location: path.locationsId
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a document from a regional knowledge base
      effect: destructive
      questions:
      - Can I delete a document from a knowledge base that lives in a particular location?
      - Is there a way to drop one regional knowledge document while keeping the base?
      instructions:
      - text: Delete regional document {document} from knowledge base {knowledge_base} in project {project}, location {location}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          location: path.locationsId
      - text: Remove {location} knowledge document {document} from {knowledge_base}.
        slots:
          location: path.locationsId
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a document in a regional knowledge base
      effect: write
      questions:
      - Can I change metadata on a document stored in a regional knowledge base?
      - Is it possible to point a regional knowledge document at a different content URI?
      instructions:
      - text: Update regional document {document} in knowledge base {knowledge_base}, project {project}, location {location} with metadata {metadata}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          location: path.locationsId
          metadata: requestBody.metadata
      - text: Change the display name of {location} knowledge document {document} to {display_name}.
        slots:
          location: path.locationsId
          document: path.documentsId
          display_name: requestBody.displayName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}:export'].post
  update:
    x-apievangelist-phrasing:
      intent: Export a regional knowledge document
      effect: write
      questions:
      - Can I copy a document from a regional knowledge base out to Cloud Storage?
      - Which destination does a regional knowledge document export write to?
      instructions:
      - text: Export regional document {document} from knowledge base {knowledge_base} in project {project}, location {location} to {gcs_destination}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          location: path.locationsId
          gcs_destination: requestBody.gcsDestination
      - text: Send {location} knowledge document {document} to Cloud Storage at {gcs_destination} with full content.
        slots:
          location: path.locationsId
          document: path.documentsId
          gcs_destination: requestBody.gcsDestination
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/knowledgeBases/{knowledgeBasesId}/documents:import'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk-import documents into a regional knowledge base
      effect: write
      questions:
      - Can I import a folder of files into a knowledge base in a specific region?
      - Does a regional knowledge import also bring in custom metadata from Cloud Storage?
      instructions:
      - text: Import files from {gcs_source} into regional knowledge base {knowledge_base} in project {project}, location {location}.
        slots:
          gcs_source: requestBody.gcsSource
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          location: path.locationsId
      - text: Bulk-import {location} knowledge documents from {gcs_source} with template {template}.
        slots:
          location: path.locationsId
          gcs_source: requestBody.gcsSource
          template: requestBody.documentTemplate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/knowledgeBases/{knowledgeBasesId}/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents in a regional knowledge base
      effect: read
      questions:
      - Which documents sit in my knowledge base in a given location?
      - Can I page through a regional knowledge base's documents with a filter?
      instructions:
      - text: List documents in regional knowledge base {knowledge_base} in project {project}, location {location}.
        slots:
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          location: path.locationsId
      - text: Show {page_size} documents at a time from {location} knowledge base {knowledge_base}.
        slots:
          page_size: query.pageSize
          location: path.locationsId
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/knowledgeBases/{knowledgeBasesId}/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a document to a regional knowledge base
      effect: write
      questions:
      - How do I add a new document to a knowledge base hosted in a particular region?
      - Can I create a regional knowledge document that reloads itself automatically?
      instructions:
      - text: Create regional document {display_name} in knowledge base {knowledge_base}, project {project}, location {location} from {content_uri}.
        slots:
          display_name: requestBody.displayName
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          location: path.locationsId
          content_uri: requestBody.contentUri
      - text: Add a {location} knowledge document {display_name} with raw content {raw_content}.
        slots:
          location: path.locationsId
          display_name: requestBody.displayName
          raw_content: requestBody.rawContent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/locations/{locationsId}/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}:reload'].post
  update:
    x-apievangelist-phrasing:
      intent: Reload a document in a regional knowledge base
      effect: write
      questions:
      - Can I trigger a re-crawl of a document stored in a regional knowledge base?
      - Is a reload of a regional knowledge document able to use a new source URI?
      instructions:
      - text: Reload regional document {document} in knowledge base {knowledge_base}, project {project}, location {location}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          location: path.locationsId
      - text: Re-fetch {location} knowledge document {document} from {content_uri}.
        slots:
          location: path.locationsId
          document: path.documentsId
          content_uri: requestBody.contentUri
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve a document from an agent's knowledge base
      effect: read
      questions:
      - What does a document attached to my ES agent's knowledge base look like?
      - Can I read one agent knowledge document by ID?
      instructions:
      - text: Get document {document} from my agent's knowledge base {knowledge_base} in project {project}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Display agent knowledge document {document} under base {knowledge_base}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a document from an agent's knowledge base
      effect: destructive
      questions:
      - Can I stop my ES agent answering from a document by deleting it from the agent's knowledge base?
      - Is removing an agent knowledge document permanent?
      instructions:
      - text: Delete document {document} from my agent's knowledge base {knowledge_base} in project {project}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Drop agent knowledge document {document} out of base {knowledge_base}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a document in an agent's knowledge base
      effect: write
      questions:
      - Can I edit the name or metadata of a document on my ES agent's knowledge base?
      - Is there a field-mask update for agent knowledge documents?
      instructions:
      - text: Update document {document} in my agent's knowledge base {knowledge_base}, project {project}, setting display name {display_name}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          display_name: requestBody.displayName
      - text: Patch agent knowledge document {document} fields {update_mask} with metadata {metadata}.
        slots:
          document: path.documentsId
          update_mask: query.updateMask
          metadata: requestBody.metadata
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/knowledgeBases/{knowledgeBasesId}/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List documents in an agent's knowledge base
      effect: read
      questions:
      - Which documents feed my ES agent's knowledge base answers?
      - Can I filter the agent knowledge document list?
      instructions:
      - text: List documents in my agent's knowledge base {knowledge_base} in project {project}.
        slots:
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Show agent knowledge documents in {knowledge_base} that match {filter}.
        slots:
          knowledge_base: path.knowledgeBasesId
          filter: query.filter
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/knowledgeBases/{knowledgeBasesId}/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a document to an agent's knowledge base
      effect: write
      questions:
      - How do I give my ES agent a new FAQ document to answer from?
      - Can I attach a document to an agent's knowledge base straight from a URL?
      instructions:
      - text: Create document {display_name} in my agent's knowledge base {knowledge_base}, project {project}, from {content_uri}.
        slots:
          display_name: requestBody.displayName
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
          content_uri: requestBody.contentUri
      - text: Attach an agent knowledge document of type {knowledge_types} to base {knowledge_base}.
        slots:
          knowledge_types: requestBody.knowledgeTypes
          knowledge_base: path.knowledgeBasesId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v2/projects/{projectsId}/agent/knowledgeBases/{knowledgeBasesId}/documents/{documentsId}:reload'].post
  update:
    x-apievangelist-phrasing:
      intent: Reload a document in an agent's knowledge base
      effect: write
      questions:
      - Can I refresh a document my ES agent uses after the source page was updated?
      - Is reloading an agent knowledge document from a different URI supported?
      instructions:
      - text: Reload document {document} in my agent's knowledge base {knowledge_base}, project {project}.
        slots:
          document: path.documentsId
          knowledge_base: path.knowledgeBasesId
          project: path.projectsId
      - text: Refresh agent knowledge document {document} using source {content_uri}.
        slots:
          document: path.documentsId
          content_uri: requestBody.contentUri
      method: generated
      generated: '2026-10-01'