GitHub Deploy API

openapi: 3.2.0
info:
  version: 1.1.4
  title: github-repos-api Deploy API
  description: 'Use the REST API to create, manage and control the workflow of public and

    private GitHub repositories.'
  license:
    name: MIT
    url: https://spdx.org/licenses/MIT
  termsOfService: https://docs.github.com/articles/github-terms-of-service
  contact:
    name: Support
    url: https://support.github.com/contact
servers:
- url: '{protocol}://{hostname}'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: api.github.com
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: https
tags:
- name: Deploy
paths:
  /repos/{owner}/{repo}/keys:
    get:
      summary: GitHub List Deploy Keys
      description: The List Deploy Keys operation retrieves all deploy keys configured for a specific GitHub repository. Deploy keys are SSH keys that grant read-only or read-write access to a single repository, commonly used for deployment automation and CI/CD pipelines. This GET endpoint requires the repository owner and name as path parameters and returns an array of deploy key objects, each containing details such as the key ID, title, public key content, verification status, creation date, and whether the key has read-only or write access. Authentication is required, and the authenticated user must have admin access to the repository to successfully retrieve the list of deploy keys.
      tags:
      - Deploy
      operationId: listDeployKeys
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/deploy-keys/deploy-keys#list-deploy-keys
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/per-page'
      - $ref: '#/components/parameters/page'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/deploy-key'
              examples:
                default:
                  $ref: '#/components/examples/deploy-key-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: deploy-keys
        subcategory: deploy-keys
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      summary: GitHub Create Deploy Key
      description: You can create a read-only deploy key.
      tags:
      - Deploy
      operationId: createDeployKey
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/deploy-keys/deploy-keys#create-a-deploy-key
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: name for the key.
                key:
                  type: string
                  description: The contents of the key.
                read_only:
                  type: boolean
                  description: 'If `true`, the key will only be able to read repository contents. Otherwise, the key will be able to read and write.


                    Deploy keys with write access can perform the same actions as an organization member with admin access, or a collaborator on a personal repository. For more information, see "[Repository permission levels for an organization](https://docs.github.com/enterprise-server@3.9/articles/repository-permission-levels-for-an-organization/)" and "[Permission levels for a user account repository](https://docs.github.com/enterprise-server@3.9/articles/permission-levels-for-a-user-account-repository/)."'
              required:
              - key
            examples:
              default:
                value:
                  title: octocat@octomac
                  key: ssh-rsa AAA...
                  read_only: true
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deploy-key'
              examples:
                default:
                  $ref: '#/components/examples/deploy-key'
          headers:
            Location:
              example: https://api.github.com/repos/octocat/Hello-World/keys/1
              schema:
                type: string
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: deploy-keys
        subcategory: deploy-keys
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repos/{owner}/{repo}/keys/{key_id}:
    get:
      summary: GitHub Get Deploy Key
      description: The Get Deploy Key operation retrieves detailed information about a specific deploy key configured for a GitHub repository. By making a GET request to /repos/{owner}/{repo}/keys/{key_id}, authenticated users with appropriate permissions can access the deploy key's metadata including its unique identifier, title, the public SSH key string, creation timestamp, verification status, and whether it has read-only or read-write access to the repository. This endpoint is useful for auditing deploy keys, verifying their configuration, or retrieving key details before performing updates or deletions. The caller must have admin access to the repository to successfully retrieve deploy key information, and the key_id parameter must correspond to an existing deploy key within the specified repository.
      tags:
      - Deploy
      operationId: getDeployKey
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/deploy-keys/deploy-keys#get-a-deploy-key
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/key-id'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deploy-key'
              examples:
                default:
                  $ref: '#/components/examples/deploy-key'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: deploy-keys
        subcategory: deploy-keys
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: GitHub Delete Deploy Key
      description: Deploy keys are immutable. If you need to update a key, remove the key and create a new one instead.
      tags:
      - Deploy
      operationId: deleteDeployKey
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/deploy-keys/deploy-keys#delete-a-deploy-key
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/key-id'
      - in: header
        name: Authorization
        schema:
          type: string
        example: example_value
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
        example: example_value
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
        example: example_value
      responses:
        '204':
          description: Response
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: deploy-keys
        subcategory: deploy-keys
      security:
      - bearerHttpAuthentication: []
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    validation_failed:
      description: Validation failed, or the endpoint has been spammed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/validation-error'
    not_found:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/basic-error'
  examples:
    deploy-key-items:
      value:
      - id: 1
        key: ssh-rsa AAA...
        url: https://api.github.com/repos/octocat/Hello-World/keys/1
        title: octocat@octomac
        verified: true
        created_at: '2014-12-10T15:53:42Z'
        read_only: true
        added_by: octocat
        last_used: '2022-01-10T15:53:42Z'
    deploy-key:
      value:
        id: 1
        key: ssh-rsa AAA...
        url: https://api.github.com/repos/octocat/Hello-World/keys/1
        title: octocat@octomac
        verified: true
        created_at: '2014-12-10T15:53:42Z'
        read_only: true
        added_by: octocat
        last_used: '2022-01-10T15:53:42Z'
  parameters:
    key-id:
      name: key_id
      description: The unique identifier of the key.
      in: path
      required: true
      schema:
        type: integer
    per-page:
      name: per_page
      description: The number of results per page (max 100). For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 30
    owner:
      name: owner
      description: The account owner of the repository. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    repo:
      name: repo
      description: The name of the repository without the `.git` extension. The name is not case sensitive.
      in: path
      required: true
      schema:
        type: string
    page:
      name: page
      description: The page number of the results to fetch. For more information, see "[Using pagination in the REST API](https://docs.github.com/enterprise-server@3.9/rest/using-the-rest-api/using-pagination-in-the-rest-api)."
      in: query
      schema:
        type: integer
        default: 1
  headers:
    link:
      example: <https://api.github.com/resource?page=2>; rel="next", <https://api.github.com/resource?page=5>; rel="last"
      schema:
        type: string
  schemas:
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        status:
          type: string
          example: open
    validation-error:
      title: Validation Error
      description: Validation Error
      type: object
      required:
      - message
      - documentation_url
      properties:
        message:
          type: string
          example: Example body text
        documentation_url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        errors:
          type: array
          items:
            type: object
            required:
            - code
            properties:
              resource:
                type: string
              field:
                type: string
              message:
                type: string
              code:
                type: string
              index:
                type: integer
              value:
                oneOf:
                - type: string
                - type: integer
                - type: array
                  items:
                    type: string
    deploy-key:
      title: Deploy Key
      description: An SSH key granting access to a single repository.
      type: object
      properties:
        id:
          type: integer
          example: 42
        key:
          type: string
          example: example_value
        url:
          type: string
          example: https://api.github.com/repos/octocat/Hello-World
        title:
          type: string
          example: Example Title
        verified:
          type: boolean
          example: true
        created_at:
          type: string
          example: '2026-04-17T12:00:00Z'
        read_only:
          type: boolean
          example: true
        added_by:
          type: string
          example: example_value
        last_used:
          type: string
          example: example_value
      required:
      - id
      - key
      - url
      - title
      - verified
      - created_at
      - read_only
  securitySchemes:
    bearerHttpAuthentication:
      description: Bearer Token
      type: http
      scheme: Bearer
externalDocs:
  description: GitHub Enterprise Developer Docs
  url: https://docs.github.com/enterprise-server@3.9/rest/