openapi: 3.1.0
info:
  title: Coolify Applications GitHub Apps API
  version: '0.1'
  description: Applications
servers:
- url: https://app.coolify.io/api/v1
  description: Coolify Cloud API. Change the host to your own instance if you are self-hosting.
tags:
- name: GitHub Apps
  description: GitHub Apps
paths:
  /github-apps:
    get:
      tags:
      - GitHub Apps
      summary: List
      description: List all GitHub apps.
      operationId: list-github-apps
      responses:
        '200':
          description: List of GitHub apps.
          content:
            application/json:
              schema:
                type: array
                items:
                  properties:
                    id:
                      type: integer
                    uuid:
                      type: string
                    name:
                      type: string
                    organization:
                      type: string
                      nullable: true
                    api_url:
                      type: string
                    html_url:
                      type: string
                    custom_user:
                      type: string
                    custom_port:
                      type: integer
                    app_id:
                      type: integer
                    installation_id:
                      type: integer
                    client_id:
                      type: string
                    private_key_id:
                      type: integer
                    is_system_wide:
                      type: boolean
                    is_public:
                      type: boolean
                    team_id:
                      type: integer
                    type:
                      type: string
                  type: object
        '401':
          $ref: '#/components/responses/401'
        '400':
          $ref: '#/components/responses/400'
      security:
      - bearerAuth: []
    post:
      tags:
      - GitHub Apps
      summary: Create GitHub App
      description: Create a new GitHub app.
      operationId: create-github-app
      requestBody:
        description: GitHub app creation payload.
        required: true
        content:
          application/json:
            schema:
              required:
              - name
              - api_url
              - html_url
              - app_id
              - installation_id
              - client_id
              - client_secret
              - private_key_uuid
              properties:
                name:
                  type: string
                  description: Name of the GitHub app.
                organization:
                  type: string
                  nullable: true
                  description: Organization to associate the app with.
                api_url:
                  type: string
                  description: API URL for the GitHub app (e.g., https://api.github.com).
                html_url:
                  type: string
                  description: HTML URL for the GitHub app (e.g., https://github.com).
                custom_user:
                  type: string
                  description: 'Custom user for SSH access (default: git).'
                custom_port:
                  type: integer
                  description: 'Custom port for SSH access (default: 22).'
                app_id:
                  type: integer
                  description: GitHub App ID from GitHub.
                installation_id:
                  type: integer
                  description: GitHub Installation ID.
                client_id:
                  type: string
                  description: GitHub OAuth App Client ID.
                client_secret:
                  type: string
                  description: GitHub OAuth App Client Secret.
                webhook_secret:
                  type: string
                  description: Webhook secret for GitHub webhooks.
                private_key_uuid:
                  type: string
                  description: UUID of an existing private key for GitHub App authentication.
                is_system_wide:
                  type: boolean
                  description: Is this app system-wide (cloud only).
              type: object
      responses:
        '201':
          description: GitHub app created successfully.
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: integer
                  uuid:
                    type: string
                  name:
                    type: string
                  organization:
                    type: string
                    nullable: true
                  api_url:
                    type: string
                  html_url:
                    type: string
                  custom_user:
                    type: string
                  custom_port:
                    type: integer
                  app_id:
                    type: integer
                  installation_id:
                    type: integer
                  client_id:
                    type: string
                  private_key_id:
                    type: integer
                  is_system_wide:
                    type: boolean
                  team_id:
                    type: integer
                type: object
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
  /github-apps/{github_app_id}/repositories:
    get:
      tags:
      - GitHub Apps
      summary: Load Repositories for a GitHub App
      description: Fetch repositories from GitHub for a given GitHub app.
      operationId: load-repositories
      parameters:
      - name: github_app_id
        in: path
        description: GitHub App ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Repositories loaded successfully.
          content:
            application/json:
              schema:
                properties:
                  repositories:
                    type: array
                    items:
                      type: object
                type: object
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
  /github-apps/{github_app_id}/repositories/{owner}/{repo}/branches:
    get:
      tags:
      - GitHub Apps
      summary: Load Branches for a GitHub Repository
      description: Fetch branches from GitHub for a given repository.
      operationId: load-branches
      parameters:
      - name: github_app_id
        in: path
        description: GitHub App ID
        required: true
        schema:
          type: integer
      - name: owner
        in: path
        description: Repository owner
        required: true
        schema:
          type: string
      - name: repo
        in: path
        description: Repository name
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Branches loaded successfully.
          content:
            application/json:
              schema:
                properties:
                  branches:
                    type: array
                    items:
                      type: object
                type: object
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
      security:
      - bearerAuth: []
  /github-apps/{github_app_id}:
    delete:
      tags:
      - GitHub Apps
      summary: Delete GitHub App
      description: Delete a GitHub app if it's not being used by any applications.
      operationId: deleteGithubApp
      parameters:
      - name: github_app_id
        in: path
        description: GitHub App ID
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: GitHub app deleted successfully
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: GitHub app deleted successfully
                type: object
        '401':
          description: Unauthorized
        '404':
          description: GitHub app not found
        '409':
          description: Conflict - GitHub app is in use
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: This GitHub app is being used by 5 application(s). Please delete all applications first.
                type: object
      security:
      - bearerAuth: []
    patch:
      tags:
      - GitHub Apps
      summary: Update GitHub App
      description: Update an existing GitHub app.
      operationId: updateGithubApp
      parameters:
      - name: github_app_id
        in: path
        description: GitHub App ID
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                name:
                  type: string
                  description: GitHub App name
                organization:
                  type: string
                  nullable: true
                  description: GitHub organization
                api_url:
                  type: string
                  description: GitHub API URL
                html_url:
                  type: string
                  description: GitHub HTML URL
                custom_user:
                  type: string
                  description: Custom user for SSH
                custom_port:
                  type: integer
                  description: Custom port for SSH
                app_id:
                  type: integer
                  description: GitHub App ID
                installation_id:
                  type: integer
                  description: GitHub Installation ID
                client_id:
                  type: string
                  description: GitHub Client ID
                client_secret:
                  type: string
                  description: GitHub Client Secret
                webhook_secret:
                  type: string
                  description: GitHub Webhook Secret
                private_key_uuid:
                  type: string
                  description: Private key UUID
                is_system_wide:
                  type: boolean
                  description: Is system wide (non-cloud instances only)
              type: object
      responses:
        '200':
          description: GitHub app updated successfully
          content:
            application/json:
              schema:
                properties:
                  message:
                    type: string
                    example: GitHub app updated successfully
                  data:
                    type: object
                    description: Updated GitHub app data
                type: object
        '401':
          description: Unauthorized
        '404':
          description: GitHub app not found
        '422':
          $ref: '#/components/responses/422'
      security:
      - bearerAuth: []
components:
  responses:
    '404':
      description: Resource not found.
      content:
        application/json:
          schema:
            properties:
              message:
                type: string
                example: Resource not found.
            type: object
    '422':
      description: Validation error.
      content:
        application/json:
          schema:
            properties:
              message:
                type: string
                example: Validation error.
              errors:
                type: object
                example:
                  name:
                  - The name field is required.
                  api_url:
                  - The api url field is required.
                  - The api url format is invalid.
                additionalProperties:
                  type: array
                  items:
                    type: string
            type: object
    '400':
      description: Invalid token.
      content:
        application/json:
          schema:
            properties:
              message:
                type: string
                example: Invalid token.
            type: object
    '401':
      description: Unauthenticated.
      content:
        application/json:
          schema:
            properties:
              message:
                type: string
                example: Unauthenticated.
            type: object
  securitySchemes:
    bearerAuth:
      type: http
      description: Go to `Keys & Tokens` / `API tokens` and create a new token. Use the token as the bearer token.
      scheme: bearer