# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Appwrite Documents DB API
  version: 1.0.0
extends: openapi/appwrite-documentsdb-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: 36
- target: $.paths['/documentsdb'].get
  update:
    x-apievangelist-phrasing:
      intent: List document databases in the project
      effect: read
      questions:
      - Which DocumentsDB databases exist in my project?
      - Can I filter my list of databases with queries?
      instructions:
      - text: List all document databases in this project.
      - text: List the databases matching {queries}.
        slots:
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a document database
      effect: write
      questions:
      - How do I create a new document database?
      - Can I provision a dedicated database with high-availability replicas instead of serverless?
      instructions:
      - text: Create a database named {name} with ID {databaseId}.
        slots:
          name: requestBody.name
          databaseId: requestBody.databaseId
      - text: Create dedicated database {databaseId} called {name} on specification {specification} with {replicas} replicas.
        slots:
          databaseId: requestBody.databaseId
          name: requestBody.name
          specification: requestBody.specification
          replicas: requestBody.replicas
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/specifications'].get
  update:
    x-apievangelist-phrasing:
      intent: List dedicated database plans and prices
      effect: read
      questions:
      - What dedicated database sizes can I choose on my plan?
      - How much does each dedicated database specification cost, including overage?
      instructions:
      - text: Show the dedicated database specifications available on my plan.
      - text: Compare the resource limits and prices of each database specification.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/transactions'].get
  update:
    x-apievangelist-phrasing:
      intent: List database transactions
      effect: read
      questions:
      - Which transactions are currently open across my databases?
      - Can I filter the transactions list with queries?
      instructions:
      - text: List all transactions across my databases.
      - text: List transactions matching {queries}.
        slots:
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/transactions'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a database transaction
      effect: write
      questions:
      - How do I start a transaction so several document writes succeed or fail together?
      - Can I set how long a transaction lives before it expires?
      instructions:
      - text: Begin a new database transaction.
      - text: Start a transaction that expires after {ttl} seconds.
        slots:
          ttl: requestBody.ttl
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/transactions/{transactionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a transaction's details
      effect: read
      questions:
      - What state is a specific transaction in?
      - Can I look up one transaction by its ID?
      instructions:
      - text: Show transaction {transactionId}.
        slots:
          transactionId: path.transactionId
      - text: Check whether transaction {transactionId} is still open.
        slots:
          transactionId: path.transactionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/transactions/{transactionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a transaction
      effect: destructive
      questions:
      - How do I throw away a transaction record entirely?
      - Can a transaction be removed by its ID?
      instructions:
      - text: Delete transaction {transactionId}.
        slots:
          transactionId: path.transactionId
      - text: Remove the transaction record {transactionId} permanently.
        slots:
          transactionId: path.transactionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/transactions/{transactionId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Commit or roll back a transaction
      effect: write
      questions:
      - How do I commit the staged changes in a transaction?
      - Can I roll back a transaction instead of committing it?
      instructions:
      - text: Commit transaction {transactionId}.
        slots:
          transactionId: path.transactionId
      - text: Roll back transaction {transactionId} with rollback set to {rollback}.
        slots:
          transactionId: path.transactionId
          rollback: requestBody.rollback
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/transactions/{transactionId}/operations'].post
  update:
    x-apievangelist-phrasing:
      intent: Stage several writes in a transaction
      effect: write
      questions:
      - How do I add a batch of staged writes to an open transaction?
      - Can I queue multiple document changes in one call inside a transaction?
      instructions:
      - text: 'Stage these operations in transaction {transactionId}: {operations}.'
        slots:
          transactionId: path.transactionId
          operations: requestBody.operations
      - text: Add a batch of staged writes to transaction {transactionId}.
        slots:
          transactionId: path.transactionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a database's metadata
      effect: read
      questions:
      - What are the settings of one particular database?
      - Can I fetch a database's metadata by its ID?
      instructions:
      - text: Show the metadata for database {databaseId}.
        slots:
          databaseId: path.databaseId
      - text: Fetch database {databaseId} and tell me whether it is enabled.
        slots:
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a database's settings
      effect: write
      questions:
      - How do I rename a database or disable it?
      - Can I change the replica count or sync mode of an existing dedicated database?
      instructions:
      - text: Rename database {databaseId} to {name}.
        slots:
          databaseId: path.databaseId
          name: requestBody.name
      - text: Set database {databaseId} named {name} to {replicas} replicas with sync mode {syncMode}.
        slots:
          databaseId: path.databaseId
          name: requestBody.name
          replicas: requestBody.replicas
          syncMode: requestBody.syncMode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a database
      effect: destructive
      questions:
      - How do I delete an entire database?
      - What API key scope is needed to delete a database?
      instructions:
      - text: Delete database {databaseId}.
        slots:
          databaseId: path.databaseId
      - text: Permanently remove database {databaseId} and everything in it.
        slots:
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections'].get
  update:
    x-apievangelist-phrasing:
      intent: List collections in a database
      effect: read
      questions:
      - Which collections does a database contain?
      - Can I search a database's collections by name?
      instructions:
      - text: List the collections in database {databaseId}.
        slots:
          databaseId: path.databaseId
      - text: Search collections in database {databaseId} for {search}.
        slots:
          databaseId: path.databaseId
          search: query.search
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a collection
      effect: write
      questions:
      - How do I create a new collection inside a database?
      - Can I define attributes and indexes when first creating a collection?
      instructions:
      - text: Create collection {name} with ID {collectionId} in database {databaseId}.
        slots:
          name: requestBody.name
          collectionId: requestBody.collectionId
          databaseId: path.databaseId
      - text: Create collection {collectionId} named {name} in database {databaseId} with document-level security {documentSecurity}.
        slots:
          collectionId: requestBody.collectionId
          name: requestBody.name
          databaseId: path.databaseId
          documentSecurity: requestBody.documentSecurity
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a collection's metadata
      effect: read
      questions:
      - What permissions and settings does one collection have?
      - Can I retrieve a collection's metadata by ID?
      instructions:
      - text: Show collection {collectionId} in database {databaseId}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Tell me whether document security is on for collection {collectionId} in database {databaseId}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a collection's settings
      effect: write
      questions:
      - How do I rename a collection or change its permissions?
      - Can I purge a collection's cached list results while updating it?
      instructions:
      - text: Rename collection {collectionId} in database {databaseId} to {name}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
          name: requestBody.name
      - text: Update collection {collectionId} in database {databaseId}, keep name {name}, and purge its cached lists.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
          name: requestBody.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a collection
      effect: destructive
      questions:
      - How do I delete a whole collection?
      - Who is allowed to delete a collection?
      instructions:
      - text: Delete collection {collectionId} from database {databaseId}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Drop the collection {collectionId} in database {databaseId} permanently.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List or query documents in a collection
      effect: read
      questions:
      - How do I fetch documents from a collection with filters?
      - Can I read uncommitted changes inside a transaction when listing documents?
      - Is it possible to cache list results for a while?
      instructions:
      - text: List documents in collection {collectionId} of database {databaseId}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Find documents in collection {collectionId} of database {databaseId} matching {queries}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or update many documents at once
      effect: write
      questions:
      - How do I bulk upsert a batch of documents into a collection?
      - Can I insert-or-update several documents in one request?
      instructions:
      - text: 'Upsert these documents into collection {collectionId} of database {databaseId}: {documents}.'
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
          documents: requestBody.documents
      - text: Bulk upsert {documents} into collection {collectionId} of database {databaseId} within transaction {transactionId}.
        slots:
          documents: requestBody.documents
          collectionId: path.collectionId
          databaseId: path.databaseId
          transactionId: requestBody.transactionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new document
      effect: write
      questions:
      - How do I add a new document to a collection?
      - Can I set permissions on a document when I create it?
      instructions:
      - text: Create document {documentId} with data {data} in collection {collectionId} of database {databaseId}.
        slots:
          documentId: requestBody.documentId
          data: requestBody.data
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Insert a new document {documentId} containing {data} into collection {collectionId} of database {databaseId} with permissions {permissions}.
        slots:
          documentId: requestBody.documentId
          data: requestBody.data
          collectionId: path.collectionId
          databaseId: path.databaseId
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete documents by query
      effect: destructive
      questions:
      - How do I delete every document matching a filter?
      - What happens if I bulk delete documents without any queries?
      instructions:
      - text: Delete all documents in collection {collectionId} of database {databaseId} matching {queries}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
          queries: query.queries
      - text: Empty collection {collectionId} in database {databaseId} of all documents.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents'].patch
  update:
    x-apievangelist-phrasing:
      intent: Bulk update documents matching a query
      effect: write
      questions:
      - How do I change a field on every document that matches a filter?
      - Can I bulk-update only specific fields across many documents?
      instructions:
      - text: Set {data} on all documents in collection {collectionId} of database {databaseId} matching {queries}.
        slots:
          data: requestBody.data
          collectionId: path.collectionId
          databaseId: path.databaseId
          queries: requestBody.queries
      - text: Apply {data} to every document in collection {collectionId} of database {databaseId}.
        slots:
          data: requestBody.data
          collectionId: path.collectionId
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one document by ID
      effect: read
      questions:
      - How do I read a single document when I know its ID?
      - Can I read a document's uncommitted version inside a transaction?
      instructions:
      - text: Get document {documentId} from collection {collectionId} of database {databaseId}.
        slots:
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Read document {documentId} in collection {collectionId} of database {databaseId} as seen by transaction {transactionId}.
        slots:
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          transactionId: query.transactionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a single document
      effect: write
      questions:
      - How do I write a document by ID whether or not it already exists?
      - Can I upsert one document and set its permissions at the same time?
      instructions:
      - text: Upsert document {documentId} in collection {collectionId} of database {databaseId} with {data}.
        slots:
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          data: requestBody.data
      - text: Create document {documentId} in collection {collectionId} of database {databaseId} if missing, otherwise overwrite it with {data}.
        slots:
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single document
      effect: destructive
      questions:
      - How do I delete one document by its ID?
      - Can I stage a single document deletion inside a transaction?
      instructions:
      - text: Delete document {documentId} from collection {collectionId} of database {databaseId}.
        slots:
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Remove document {documentId} in collection {collectionId} of database {databaseId} as part of transaction {transactionId}.
        slots:
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          transactionId: query.transactionId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Partially update one document
      effect: write
      questions:
      - How do I change just a few fields on an existing document?
      - Can I update a single document's permissions without touching its data?
      instructions:
      - text: Update document {documentId} in collection {collectionId} of database {databaseId} with {data}.
        slots:
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          data: requestBody.data
      - text: Change the permissions of document {documentId} in collection {collectionId} of database {databaseId} to {permissions}.
        slots:
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          permissions: requestBody.permissions
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/decrement'].patch
  update:
    x-apievangelist-phrasing:
      intent: Decrement a numeric field on a document
      effect: write
      questions:
      - How do I atomically subtract from a counter on a document?
      - Can I stop a decrement from going below a minimum value?
      instructions:
      - text: Decrease {attribute} on document {documentId} in collection {collectionId} of database {databaseId} by {value}.
        slots:
          attribute: path.attribute
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          value: requestBody.value
      - text: Decrement {attribute} of document {documentId} in collection {collectionId}, database {databaseId}, but not below {min}.
        slots:
          attribute: path.attribute
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          min: requestBody.min
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/documents/{documentId}/{attribute}/increment'].patch
  update:
    x-apievangelist-phrasing:
      intent: Increment a numeric field on a document
      effect: write
      questions:
      - How do I atomically add to a counter on a document?
      - Can I cap an increment at a maximum value?
      instructions:
      - text: Increase {attribute} on document {documentId} in collection {collectionId} of database {databaseId} by {value}.
        slots:
          attribute: path.attribute
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          value: requestBody.value
      - text: Increment {attribute} of document {documentId} in collection {collectionId}, database {databaseId}, up to at most {max}.
        slots:
          attribute: path.attribute
          documentId: path.documentId
          collectionId: path.collectionId
          databaseId: path.databaseId
          max: requestBody.max
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/indexes'].get
  update:
    x-apievangelist-phrasing:
      intent: List a collection's indexes
      effect: read
      questions:
      - Which indexes are defined on a collection?
      - Can I filter a collection's index list with queries?
      instructions:
      - text: List the indexes on collection {collectionId} in database {databaseId}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Show indexes on collection {collectionId} in database {databaseId} matching {queries}.
        slots:
          collectionId: path.collectionId
          databaseId: path.databaseId
          queries: query.queries
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/indexes'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an index on a collection
      effect: write
      questions:
      - How do I add an index so my document queries run faster?
      - Can I create a unique or fulltext index across several attributes?
      instructions:
      - text: Create a {type} index {key} on {attributes} in collection {collectionId} of database {databaseId}.
        slots:
          type: requestBody.type
          key: requestBody.key
          attributes: requestBody.attributes
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Add a unique index {key} over {attributes} to collection {collectionId} in database {databaseId} with type {type}.
        slots:
          key: requestBody.key
          attributes: requestBody.attributes
          collectionId: path.collectionId
          databaseId: path.databaseId
          type: requestBody.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/indexes/{key}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an index's definition
      effect: read
      questions:
      - What attributes does a particular index cover?
      - Can I look up one index on a collection by its key?
      instructions:
      - text: Show index {key} on collection {collectionId} in database {databaseId}.
        slots:
          key: path.key
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Tell me which attributes index {key} covers in collection {collectionId}, database {databaseId}.
        slots:
          key: path.key
          collectionId: path.collectionId
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/collections/{collectionId}/indexes/{key}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an index
      effect: destructive
      questions:
      - How do I drop an index I no longer need?
      - Can I remove an index from a collection by key?
      instructions:
      - text: Delete index {key} from collection {collectionId} in database {databaseId}.
        slots:
          key: path.key
          collectionId: path.collectionId
          databaseId: path.databaseId
      - text: Drop the {key} index on collection {collectionId}, database {databaseId}.
        slots:
          key: path.key
          collectionId: path.collectionId
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/failovers'].post
  update:
    x-apievangelist-phrasing:
      intent: Fail over a dedicated database to a replica
      effect: write
      questions:
      - How do I manually promote a replica to primary on my dedicated database?
      - Can I repair a database stuck mid-operation by forcing a failover?
      instructions:
      - text: Trigger a failover on dedicated database {databaseId}.
        slots:
          databaseId: path.databaseId
      - text: Fail over database {databaseId} and promote replica {targetReplicaId}.
        slots:
          databaseId: path.databaseId
          targetReplicaId: requestBody.targetReplicaId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/operations'].get
  update:
    x-apievangelist-phrasing:
      intent: List a dedicated database's lifecycle history
      effect: read
      questions:
      - What provisioning, backup and restore actions have run on my dedicated database?
      - Can I see only the failed lifecycle actions for a database?
      instructions:
      - text: Show the lifecycle history of dedicated database {databaseId}, newest first.
        slots:
          databaseId: path.databaseId
      - text: List the last {limit} lifecycle actions on database {databaseId} with status {status}.
        slots:
          limit: query.limit
          databaseId: path.databaseId
          status: query.status
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/replicas'].get
  update:
    x-apievangelist-phrasing:
      intent: Check replication status and lag
      effect: read
      questions:
      - How far behind are my database replicas?
      - What sync mode is my high-availability database using?
      instructions:
      - text: Show the replica statuses and replication lag for database {databaseId}.
        slots:
          databaseId: path.databaseId
      - text: Check the high-availability setup of database {databaseId}.
        slots:
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/documentsdb/{databaseId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a dedicated database's health
      effect: read
      questions:
      - Is my dedicated database healthy and ready right now?
      - What are the uptime, connection info and volume usage of my database?
      instructions:
      - text: Check the health of dedicated database {databaseId}.
        slots:
          databaseId: path.databaseId
      - text: Show uptime, readiness and volume info for database {databaseId}.
        slots:
          databaseId: path.databaseId
      method: generated
      generated: '2026-09-26'