Appwrite · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Appwrite VCS API

12 actions 12 updates phrasing extends openapi/appwrite-vcs-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for Appwrite's API. It is a proposal applied on top of the contract, not a document Appwrite publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 12

$.info

$.paths['/vcs/github/installations/{installationId}/detections'].post

$.paths['/vcs/github/installations/{installationId}/providerRepositories'].get

$.paths['/vcs/github/installations/{installationId}/providerRepositories'].post

$.paths['/vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}'].get

$.paths['/vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}/branches'].get

$.paths['/vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}/contents'].get

$.paths['/vcs/github/installations/{installationId}/repositories/{repositoryId}'].patch

$.paths['/vcs/installations'].get

$.paths['/vcs/installations/{installationId}'].get

$.paths['/vcs/installations/{installationId}'].delete

$.paths['/vcs/installations/{installationId}/namespaces'].get

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Appwrite VCS API
  version: 1.0.0
extends: openapi/appwrite-vcs-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: 11
- target: $.paths['/vcs/github/installations/{installationId}/detections'].post
  update:
    x-apievangelist-phrasing:
      intent: Detect a repository's language and runtime
      effect: read
      questions:
      - Can Appwrite work out which runtime a GitHub repository needs before I deploy it?
      - How does runtime detection decide the language of a connected repo?
      - Can I run detection against a subfolder rather than the repository root?
      instructions:
      - text: Detect the runtime for repository {providerRepositoryId} on installation {installationId} as a {type}.
        slots:
          providerRepositoryId: requestBody.providerRepositoryId
          installationId: path.installationId
          type: requestBody.type
      - text: Scan the {providerRootDirectory} folder of repo {providerRepositoryId} via installation {installationId} and tell me its language, treating it as a {type}.
        slots:
          providerRootDirectory: requestBody.providerRootDirectory
          providerRepositoryId: requestBody.providerRepositoryId
          installationId: path.installationId
          type: requestBody.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/github/installations/{installationId}/providerRepositories'].get
  update:
    x-apievangelist-phrasing:
      intent: List GitHub repositories on an installation
      effect: read
      questions:
      - Which GitHub repositories can my Appwrite installation see?
      - Can I search the repositories available to an installation by name?
      - Does the repository list show each repo's detected runtime and last push date?
      instructions:
      - text: List the repositories available through installation {installationId} for a {type}.
        slots:
          installationId: path.installationId
          type: query.type
      - text: Search repositories on installation {installationId} for {search}, for a {type}.
        slots:
          installationId: path.installationId
          search: query.search
          type: query.type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/github/installations/{installationId}/providerRepositories'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new GitHub repository
      effect: write
      questions:
      - Can I create a brand-new GitHub repository straight from Appwrite?
      - Is it possible to make the new repo private or put it under an organization?
      instructions:
      - text: Create a GitHub repository named {name} through installation {installationId}, private set to {private}.
        slots:
          name: requestBody.name
          installationId: path.installationId
          private: requestBody.private
      - text: 'Create repo {name} under the {providerNamespace} organization using installation {installationId}, private: {private}.'
        slots:
          name: requestBody.name
          providerNamespace: requestBody.providerNamespace
          installationId: path.installationId
          private: requestBody.private
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one GitHub repository's details
      effect: read
      questions:
      - How do I check the visibility and latest push date of one connected repository?
      - What details can I pull for a single GitHub repo on my installation?
      instructions:
      - text: Show repository {providerRepositoryId} from installation {installationId}.
        slots:
          providerRepositoryId: path.providerRepositoryId
          installationId: path.installationId
      - text: Get the name, owner and visibility of repo {providerRepositoryId} on installation {installationId}.
        slots:
          providerRepositoryId: path.providerRepositoryId
          installationId: path.installationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}/branches'].get
  update:
    x-apievangelist-phrasing:
      intent: List a repository's branches
      effect: read
      questions:
      - Which branches exist in a GitHub repo connected to my project?
      - Can I search a repository's branch names and page through them?
      instructions:
      - text: List the branches of repo {providerRepositoryId} on installation {installationId}.
        slots:
          providerRepositoryId: path.providerRepositoryId
          installationId: path.installationId
      - text: Find branches matching {search} in repository {providerRepositoryId} via installation {installationId}.
        slots:
          search: query.search
          providerRepositoryId: path.providerRepositoryId
          installationId: path.installationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}/contents'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse files and folders in a repository
      effect: read
      questions:
      - How can I see the files and folders inside a connected GitHub repo?
      - Can I browse a specific directory at a given branch or commit?
      instructions:
      - text: Show the files at the root of repo {providerRepositoryId} on installation {installationId}.
        slots:
          providerRepositoryId: path.providerRepositoryId
          installationId: path.installationId
      - text: List the contents of {providerRootDirectory} at {providerReference} in repo {providerRepositoryId} via installation {installationId}.
        slots:
          providerRootDirectory: query.providerRootDirectory
          providerReference: query.providerReference
          providerRepositoryId: path.providerRepositoryId
          installationId: path.installationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/github/installations/{installationId}/repositories/{repositoryId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Authorize deployments for an outside pull request
      effect: write
      questions:
      - How do I allow a pull request from an external contributor to get a preview deployment?
      - Can I authorize a pull request that was already approved once before?
      instructions:
      - text: Authorize pull request {providerPullRequestId} in repository {repositoryId} on installation {installationId} for deployment.
        slots:
          providerPullRequestId: requestBody.providerPullRequestId
          repositoryId: path.repositoryId
          installationId: path.installationId
      - text: Approve the external contribution in PR {providerPullRequestId} so it builds a preview for repo {repositoryId} via installation {installationId}.
        slots:
          providerPullRequestId: requestBody.providerPullRequestId
          repositoryId: path.repositoryId
          installationId: path.installationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/installations'].get
  update:
    x-apievangelist-phrasing:
      intent: List the project's VCS installations
      effect: read
      questions:
      - What version control installations are connected to my Appwrite project?
      - Can I search my VCS installations by organization?
      instructions:
      - text: List all VCS installations in this project.
      - text: Search VCS installations for {search}.
        slots:
          search: query.search
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/installations/{installationId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one VCS installation
      effect: read
      questions:
      - Which provider and organization is a particular VCS installation tied to?
      - How do I view the configuration of one installation by ID?
      instructions:
      - text: Show VCS installation {installationId}.
        slots:
          installationId: path.installationId
      - text: Get the provider and organization for installation {installationId}.
        slots:
          installationId: path.installationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/installations/{installationId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a VCS installation
      effect: destructive
      questions:
      - How do I disconnect a GitHub installation from my project?
      - Does removing an installation also drop its linked repositories from the project?
      instructions:
      - text: Delete VCS installation {installationId}.
        slots:
          installationId: path.installationId
      - text: Disconnect installation {installationId} and its repositories from this project.
        slots:
          installationId: path.installationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/vcs/installations/{installationId}/namespaces'].get
  update:
    x-apievangelist-phrasing:
      intent: List namespaces an installation can use
      effect: read
      questions:
      - Which organizations or groups can my VCS installation browse?
      - Does the namespace list include my personal account as well as organizations?
      instructions:
      - text: List the namespaces available to installation {installationId}.
        slots:
          installationId: path.installationId
      - text: Search namespaces on installation {installationId} for {search}.
        slots:
          installationId: path.installationId
          search: query.search
      method: generated
      generated: '2026-09-26'