Appwrite VCS API

openapi: 3.0.0
info:
  title: Appwrite Vcs API
  description: Appwrite backend as a service cuts up to 70% of the time and costs required for building a modern application. We abstract and simplify common development tasks behind a REST APIs, to help you develop your app in a fast and secure way. For full API documentation and tutorials go to [https://appwrite.io/docs](https://appwrite.io/docs)
  version: 2.0.0
  termsOfService: https://appwrite.io/policy/terms
  contact:
    name: Appwrite Team
    url: https://appwrite.io/support
    email: team@appwrite.io
  license:
    name: BSD-3-Clause
    url: https://raw.githubusercontent.com/appwrite/appwrite/master/LICENSE
servers:
- url: https://cloud.appwrite.io/v1
  description: Appwrite Cloud endpoint.
- url: https://{region}.cloud.appwrite.io/v1
  description: Appwrite Cloud regional endpoint. Replace `{region}` with your project region.
  variables:
    region:
      default: fra
      description: Appwrite Cloud region.
tags:
- name: vcs
  description: The VCS service allows you to interact with providers like GitHub, GitLab etc.
paths:
  /vcs/github/installations/{installationId}/detections:
    post:
      summary: Create repository detection
      operationId: vcsCreateRepositoryDetection
      tags:
      - vcs
      description: Analyze a GitHub repository to automatically detect the programming language and runtime environment. This endpoint scans the repository's files and language statistics to determine the appropriate runtime settings for your function. The GitHub installation must be properly configured and the repository must be accessible through your installation for this endpoint to work.
      responses:
        '200':
          description: DetectionRuntime, or DetectionFramework
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/detectionRuntime'
                - $ref: '#/components/schemas/detectionFramework'
                discriminator:
                  propertyName: type
                  mapping:
                    runtime: '#/components/schemas/detectionRuntime'
                    framework: '#/components/schemas/detectionFramework'
      deprecated: false
      x-appwrite:
        group: repositories
        demo: vcs/create-repository-detection.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                providerRepositoryId:
                  description: Repository Id
                  type: string
                  example: <PROVIDER_REPOSITORY_ID>
                type:
                  description: 'Detector type. Must be one of the following: runtime, framework'
                  type: string
                  example: runtime
                  title: VCSDetectionType
                  oneOf:
                  - type: string
                    enum:
                    - runtime
                    title: runtime
                  - type: string
                    enum:
                    - framework
                    title: framework
                providerRootDirectory:
                  description: Path to Root Directory
                  type: string
                  default: ''
                  example: <PROVIDER_ROOT_DIRECTORY>
              required:
              - providerRepositoryId
              - type
  /vcs/github/installations/{installationId}/providerRepositories:
    get:
      summary: List repositories
      operationId: vcsListRepositories
      tags:
      - vcs
      description: Get a list of GitHub repositories available through your installation. This endpoint returns repositories with their basic information, detected runtime environments, and latest push dates. You can optionally filter repositories using a search term. Each repository's runtime is automatically detected based on its contents and language statistics. The GitHub installation must be properly configured for this endpoint to work.
      responses:
        '200':
          description: Runtime Provider Repositories List, or Framework Provider Repositories List
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/providerRepositoryRuntimeList'
                - $ref: '#/components/schemas/providerRepositoryFrameworkList'
                discriminator:
                  propertyName: type
                  mapping:
                    runtime: '#/components/schemas/providerRepositoryRuntimeList'
                    framework: '#/components/schemas/providerRepositoryFrameworkList'
      deprecated: false
      x-appwrite:
        group: repositories
        demo: vcs/list-repositories.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
      - name: type
        description: 'Detector type. Must be one of the following: runtime, framework'
        required: true
        schema:
          type: string
          example: runtime
          title: VCSDetectionType
          oneOf:
          - type: string
            enum:
            - runtime
            title: runtime
          - type: string
            enum:
            - framework
            title: framework
        in: query
      - name: search
        description: 'Search term to filter your list results. Max length: 256 chars.'
        required: false
        schema:
          type: string
          example: <SEARCH>
          default: ''
        in: query
      - name: queries
        description: Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit, offset, and equal on namespace.
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
    post:
      summary: Create repository
      operationId: vcsCreateRepository
      tags:
      - vcs
      description: Create a new GitHub repository through your installation. This endpoint allows you to create either a public or private repository by specifying a name and visibility setting. The repository will be created under your GitHub user account or organization, depending on your installation type. The GitHub installation must be properly configured and have the necessary permissions for repository creation.
      responses:
        '200':
          description: ProviderRepository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/providerRepository'
      deprecated: false
      x-appwrite:
        group: repositories
        demo: vcs/create-repository.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  description: Repository name (slug)
                  type: string
                  example: <NAME>
                private:
                  description: Mark repository public or private
                  type: boolean
                  example: false
                providerNamespace:
                  description: Namespace of the git repository. Defaults to the installation's own namespace.
                  type: string
                  default: ''
                  example: <PROVIDER_NAMESPACE>
              required:
              - name
              - private
  /vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}:
    get:
      summary: Get repository
      operationId: vcsGetRepository
      tags:
      - vcs
      description: Get detailed information about a specific GitHub repository from your installation. This endpoint returns repository details including its ID, name, visibility status, organization, and latest push date. The GitHub installation must be properly configured and have access to the requested repository for this endpoint to work.
      responses:
        '200':
          description: ProviderRepository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/providerRepository'
      deprecated: false
      x-appwrite:
        group: repositories
        demo: vcs/get-repository.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
      - name: providerRepositoryId
        description: Repository Id
        required: true
        schema:
          type: string
          example: <PROVIDER_REPOSITORY_ID>
        in: path
  /vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}/branches:
    get:
      summary: List repository branches
      operationId: vcsListRepositoryBranches
      tags:
      - vcs
      description: 'Get a list of branches from a GitHub repository in your installation. This endpoint supports filtering by a search term and pagination using query strings such as `Query.limit()`, `Query.offset()`, `Query.cursorAfter()`, and `Query.cursorBefore()`. It returns branch names along with the total number of matches. The GitHub installation must be properly configured and have access to the requested repository for this endpoint to work.

        '
      responses:
        '200':
          description: Branches List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branchList'
      deprecated: false
      x-appwrite:
        group: repositories
        demo: vcs/list-repository-branches.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
      - name: providerRepositoryId
        description: Repository Id
        required: true
        schema:
          type: string
          example: <PROVIDER_REPOSITORY_ID>
        in: path
      - name: search
        description: 'Search term to filter your list results. Max length: 256 chars.'
        required: false
        schema:
          type: string
          example: <SEARCH>
          default: ''
        in: query
      - name: queries
        description: Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit, offset, cursorAfter, and cursorBefore
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
  /vcs/github/installations/{installationId}/providerRepositories/{providerRepositoryId}/contents:
    get:
      summary: Get files and directories of a VCS repository
      operationId: vcsGetRepositoryContents
      tags:
      - vcs
      description: Get a list of files and directories from a GitHub repository connected to your project. This endpoint returns the contents of a specified repository path, including file names, sizes, and whether each item is a file or directory. The GitHub installation must be properly configured and the repository must be accessible through your installation for this endpoint to work.
      responses:
        '200':
          description: VCS Content List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/vcsContentList'
      deprecated: false
      x-appwrite:
        group: repositories
        demo: vcs/get-repository-contents.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
      - name: providerRepositoryId
        description: Repository Id
        required: true
        schema:
          type: string
          example: <PROVIDER_REPOSITORY_ID>
        in: path
      - name: providerRootDirectory
        description: Path to get contents of nested directory
        required: false
        schema:
          type: string
          example: <PROVIDER_ROOT_DIRECTORY>
          default: ''
        in: query
      - name: providerReference
        description: Git reference (branch, tag, commit) to get contents from
        required: false
        schema:
          type: string
          example: <PROVIDER_REFERENCE>
          default: ''
        in: query
  /vcs/github/installations/{installationId}/repositories/{repositoryId}:
    patch:
      summary: Update external deployment (authorize)
      operationId: vcsUpdateExternalDeployments
      tags:
      - vcs
      description: Authorize and create deployments for a GitHub pull request in your project. This endpoint allows external contributions by creating deployments from pull requests, enabling preview environments for code review. The pull request must be open and not previously authorized. The GitHub installation must be properly configured and have access to both the repository and pull request for this endpoint to work.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: repositories
        demo: vcs/update-external-deployments.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
      - name: repositoryId
        description: VCS Repository Id
        required: true
        schema:
          type: string
          example: <REPOSITORY_ID>
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                providerPullRequestId:
                  description: GitHub Pull Request Id
                  type: string
                  example: <PROVIDER_PULL_REQUEST_ID>
              required:
              - providerPullRequestId
  /vcs/installations:
    get:
      summary: List installations
      operationId: vcsListInstallations
      tags:
      - vcs
      description: 'List all VCS installations configured for the current project. This endpoint returns a list of installations including their provider, organization, and other configuration details.

        '
      responses:
        '200':
          description: Installations List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/installationList'
      deprecated: false
      x-appwrite:
        group: installations
        demo: vcs/list-installations.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: queries
        description: 'Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Maximum of 100 queries are allowed, each 4096 characters long. You may filter on the following attributes: provider, organization'
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
      - name: search
        description: 'Search term to filter your list results. Max length: 256 chars.'
        required: false
        schema:
          type: string
          example: <SEARCH>
          default: ''
        in: query
      - name: total
        description: When set to false, the total count returned will be 0 and will not be calculated.
        required: false
        schema:
          type: boolean
          example: false
          default: true
        in: query
  /vcs/installations/{installationId}:
    get:
      summary: Get installation
      operationId: vcsGetInstallation
      tags:
      - vcs
      description: 'Get a VCS installation by its unique ID. This endpoint returns the installation''s details including its provider, organization, and configuration. '
      responses:
        '200':
          description: Installation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/installation'
      deprecated: false
      x-appwrite:
        group: installations
        demo: vcs/get-installation.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
    delete:
      summary: Delete installation
      operationId: vcsDeleteInstallation
      tags:
      - vcs
      description: Delete a VCS installation by its unique ID. This endpoint removes the installation and all its associated repositories from the project.
      responses:
        '204':
          description: No content
      deprecated: false
      x-appwrite:
        group: installations
        demo: vcs/delete-installation.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.write
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
  /vcs/installations/{installationId}/namespaces:
    get:
      summary: List namespaces
      operationId: vcsListNamespaces
      tags:
      - vcs
      description: List provider namespaces available to a VCS installation. This can include the user personal namespace and any groups or organizations the installation can browse.
      responses:
        '200':
          description: VCS Namespaces List
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/vcsNamespaceList'
      deprecated: false
      x-appwrite:
        group: namespaces
        demo: vcs/list-namespaces.md
        rate-limit: 0
        rate-time: 3600
        rate-key: url:{url},ip:{ip}
        scope: vcs.read
        platforms:
        - console
        packaging: false
        public: true
        auth:
          console:
            Project: []
      security:
      - Project: []
      parameters:
      - name: installationId
        description: Installation Id
        required: true
        schema:
          type: string
          example: <INSTALLATION_ID>
        in: path
      - name: search
        description: 'Search term to filter your list results. Max length: 256 chars.'
        required: false
        schema:
          type: string
          example: <SEARCH>
          default: ''
        in: query
      - name: queries
        description: Array of query strings generated using the Query class provided by the SDK. [Learn more about queries](https://appwrite.io/docs/queries). Only supported methods are limit and offset
        required: false
        schema:
          type: array
          items:
            type: string
          default: []
        in: query
components:
  schemas:
    branch:
      description: Branch
      type: object
      properties:
        name:
          type: string
          description: Branch Name.
          example: main
      required:
      - name
      example:
        name: main
    branchList:
      description: Branches List
      type: object
      properties:
        total:
          type: integer
          description: Total number of branches that matched your query.
          format: int32
          example: 5
        branches:
          type: array
          description: List of branches.
          items:
            $ref: '#/components/schemas/branch'
          example: []
      required:
      - total
      - branches
      example:
        total: 5
        branches: ''
    detectionFramework:
      description: DetectionFramework
      type: object
      properties:
        type:
          description: Repository detection type.
          example: framework
          type: string
          oneOf:
          - type: string
            enum:
            - framework
            title: framework
        variables:
          type: array
          description: Environment variables found in .env files
          items:
            $ref: '#/components/schemas/detectionVariable'
          example: []
          nullable: true
        framework:
          type: string
          description: Framework
          example: nuxt
        installCommand:
          type: string
          description: Site Install Command
          example: npm install
        buildCommand:
          type: string
          description: Site Build Command
          example: npm run build
        outputDirectory:
          type: string
          description: Site Output Directory
          example: dist
      required:
      - type
      - framework
      - installCommand
      - buildCommand
      - outputDirectory
      example:
        type: framework
        variables: {}
        framework: nuxt
        installCommand: npm install
        buildCommand: npm run build
        outputDirectory: dist
    detectionRuntime:
      description: DetectionRuntime
      type: object
      properties:
        type:
          description: Repository detection type.
          example: runtime
          type: string
          oneOf:
          - type: string
            enum:
            - runtime
            title: runtime
        variables:
          type: array
          description: Environment variables found in .env files
          items:
            $ref: '#/components/schemas/detectionVariable'
          example: []
          nullable: true
        runtime:
          type: string
          description: Runtime
          example: node
        entrypoint:
          type: string
          description: Function Entrypoint
          example: index.js
        commands:
          type: string
          description: Function install and build commands
          example: npm install && npm run build
      required:
      - type
      - runtime
      - entrypoint
      - commands
      example:
        type: runtime
        variables: {}
        runtime: node
        entrypoint: index.js
        commands: npm install && npm run build
    detectionVariable:
      description: DetectionVariable
      type: object
      properties:
        name:
          type: string
          description: Name of environment variable
          example: NODE_ENV
        value:
          type: string
          description: Value of environment variable
          example: production
      required:
      - name
      - value
      example:
        name: NODE_ENV
        value: production
    installation:
      description: Installation
      type: object
      properties:
        $id:
          type: string
          description: Function ID.
          example: 5e5ea5c16897e
        $createdAt:
          type: string
          description: Function creation date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        $updatedAt:
          type: string
          description: Function update date in ISO 8601 format.
          example: '2020-10-15T06:38:00.000+00:00'
        provider:
          type: string
          description: VCS (Version Control System) provider name.
          example: github
        organization:
          type: string
          description: VCS (Version Control System) organization name.
          example: appwrite
        providerInstallationId:
          type: string
          description: VCS (Version Control System) installation ID.
          example: '5322'
      required:
      - $id
      - $createdAt
      - $updatedAt
      - provider
      - organization
      - providerInstallationId
      example:
        $id: 5e5ea5c16897e
        $createdAt: '2020-10-15T06:38:00.000+00:00'
        $updatedAt: '2020-10-15T06:38:00.000+00:00'
        provider: github
        organization: appwrite
        providerInstallationId: '5322'
    installationList:
      description: Installations List
      type: object
      properties:
        total:
          type: integer
          description: Total number of installations that matched your query.
          format: int32
          example: 5
        installations:
          type: array
          description: List of installations.
          items:
            $ref: '#/components/schemas/installation'
          example: []
      required:
      - total
      - installations
      example:
        total: 5
        installations: ''
    providerRepository:
      description: ProviderRepository
      type: object
      properties:
        id:
          type: string
          description: VCS (Version Control System) repository ID.
          example: 5e5ea5c16897e
        name:
          type: string
          description: VCS (Version Control System) repository name.
          example: appwrite
        organization:
          type: string
          description: VCS (Version Control System) organization name
          example: appwrite
        provider:
          type: string
          description: VCS (Version Control System) provider name.
          example: github
        private:
          type: boolean
          description: Is VCS (Version Control System) repository private?
          example: true
        defaultBranch:
          type: string
          description: VCS (Version Control System) repository's default branch name.
          example: main
        providerInstallationId:
          type: string
          description: VCS (Version Control System) installation ID.
          example: '108104697'
        authorized:
          type: boolean
          description: Is VCS (Version Control System) repository authorized for the installation?
          example: true
        pushedAt:
          type: string
          description: Last commit date in ISO 8601 format.
          example: datetime
        variables:
          type: array
          description: Environment variables found in .env files
          items:
            type: string
          example:
          - PORT
          - NODE_ENV
      required:
      - id
      - name
      - organization
      - provider
      - private
      - defaultBranch
      - providerInstallationId
      - authorized
      - pushedAt
      - variables
      example:
        id: 5e5ea5c16897e
        name: appwrite
        organization: appwrite
        provider: github
        private: true
        defaultBranch: main
        providerInstallationId: '108104697'
        authorized: true
        pushedAt: datetime
        variables:
        - PORT
        - NODE_ENV
    providerRepositoryFramework:
      description: ProviderRepositoryFramework
      type: object
      properties:
        id:
          type: string
          description: VCS (Version Control System) repository ID.
          example: 5e5ea5c16897e
        name:
          type: string
          description: VCS (Version Control System) repository name.
          example: appwrite
        organization:
          type: string
          description: VCS (Version Control System) organization name
          example: appwrite
        provider:
          type: string
          description: VCS (Version Control System) provider name.
          example: github
        private:
          type: boolean
          description: Is VCS (Version Control System) repository private?
          example: true
        defaultBranch:
          type: string
          description: VCS (Version Control System) repository's default branch name.
          example: main
        providerInstallationId:
          type: string
          description: VCS (Version Control System) installation ID.
          example: '108104697'
        authorized:
          type: boolean
          description: Is VCS (Version Control System) repository authorized for the installation?
          example: true
        pushedAt:
          type: string
          description: Last commit date in ISO 8601 format.
          example: datetime
        variables:
          type: array
          description: Environment variables found in .env files
          items:
            type: string
          example:
          - PORT
          - NODE_ENV
        framework:
          type: string
          description: Auto-detected framework. Empty if type is not "framework".
          example: nextjs
      required:
      - id
      - name
      - organization
      - provider
      - private
      - defaultBranch
      - providerInstallationId
      - authorized
      - pushedAt
      - variables
      - framework
      example:
        id: 5e5ea5c16897e
        name: appwrite
        organization: appwrite
        provider: github
        private: true
        defaultBranch: main
        providerInstallationId: '108104697'
        authorized: true
        pushedAt: datetime
        variables:
        - PORT
        - NODE_ENV
        framework: nextjs
    providerRepositoryFrameworkList:
      description: Framework Provider Repositories List
      type: object
      properties:
        total:
          type: integer
          description: Total number of frameworkProviderRepositories that matched your query.
          format: int32
          example: 5
        frameworkProviderRe

# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/appwrite/refs/heads/main/openapi/appwrite-vcs-api-openapi.yml