GitHub Tags API

openapi: 3.0.3
info:
  version: 1.1.4
  title: GitHub Application About Tags API
  description: 'Use the REST API to retrieve information about GitHub Apps and GitHub App

    installations.'
  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?tags=dotcom-rest-api
  x-github-plan: ghes
  x-github-release: 3.9
servers:
- url: '{protocol}://{hostname}/api/v3'
  variables:
    hostname:
      description: Self-hosted Enterprise Server hostname
      default: HOSTNAME
    protocol:
      description: Self-hosted Enterprise Server protocol
      default: http
tags:
- name: Tags
paths:
  /repos/{owner}/{repo}/git/tags:
    post:
      summary: Create Tag Object
      description: 'Note that creating a tag object does not create the reference that makes a tag in Git. If you want to create an annotated tag in Git, you have to do this call to create the tag object, and then [create](https://docs.github.com/enterprise-server@3.9/rest/git/refs#create-a-reference) the `refs/tags/[tag]` reference. If you want to create a lightweight tag, you only have to [create](https://docs.github.com/enterprise-server@3.9/rest/git/refs#create-a-reference) the tag reference - this call would be unnecessary.


        **Signature verification object**


        The response will include a `verification` object that describes the result of verifying the commit''s signature. The following fields are included in the `verification` object:


        | Name | Type | Description |

        | - | - | -- |

        | `verified` | `boolean` | Indicates whether GitHub considers the signature in this commit to be verified. |

        | `reason` | `string` | The reason for verified value. Possible values and their meanings are enumerated in table below. |

        | `signature` | `string` | The signature that was extracted from the commit. |

        | `payload` | `string` | The value that was signed. |


        These are the possible values for `reason` in the `verification` object:


        | Value | Description |

        | -- | -- |

        | `expired_key` | The key that made the signature is expired. |

        | `not_signing_key` | The "signing" flag is not among the usage flags in the GPG key that made the signature. |

        | `gpgverify_error` | There was an error communicating with the signature verification service. |

        | `gpgverify_unavailable` | The signature verification service is currently unavailable. |

        | `unsigned` | The object does not include a signature. |

        | `unknown_signature_type` | non-PGP signature was found in the commit. |

        | `no_user` | No user was associated with the `committer` email address in the commit. |

        | `unverified_email` | The `committer` email address in the commit was associated with a user, but the email address is not verified on their account. |

        | `bad_email` | The `committer` email address in the commit is not included in the identities of the PGP key that made the signature. |

        | `unknown_key` | The key that made the signature has not been registered with any user''s account. |

        | `malformed_signature` | There was an error parsing the signature. |

        | `invalid` | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |

        | `valid` | None of the above errors applied, so the signature is considered to be verified. |'
      tags:
      - Tags
      operationId: createTagObject
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/git/tags#create-a-tag-object
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                tag:
                  type: string
                  description: The tag's name. This is typically a version (e.g., "v0.0.1").
                message:
                  type: string
                  description: The tag message.
                object:
                  type: string
                  description: The SHA of the git object this is tagging.
                type:
                  type: string
                  description: The type of the object we're tagging. Normally this is a `commit` but it can also be a `tree` or a `blob`.
                  enum:
                  - commit
                  - tree
                  - blob
                tagger:
                  type: object
                  description: An object with information about the individual creating the tag.
                  properties:
                    name:
                      type: string
                      description: The name of the author of the tag
                    email:
                      type: string
                      description: The email of the author of the tag
                    date:
                      type: string
                      format: date-time
                      description: 'When this object was tagged. This is a timestamp in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format: `YYYY-MM-DDTHH:MM:SSZ`.'
                  required:
                  - name
                  - email
              required:
              - tag
              - message
              - object
              - type
            examples:
              default:
                value:
                  tag: v0.0.1
                  message: initial version
                  object: c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c
                  type: commit
                  tagger:
                    name: Monalisa Octocat
                    email: octocat@github.com
                    date: '2011-06-17T14:53:35-07:00'
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/git-tag'
              examples:
                default:
                  $ref: '#/components/examples/git-tag'
          headers:
            Location:
              example: https://api.github.com/repos/octocat/Hello-World/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac
              schema:
                type: string
        '422':
          $ref: '#/components/responses/validation_failed'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: git
        subcategory: tags
      security:
      - bearerHttpAuthentication: []
  /repos/{owner}/{repo}/git/tags/{tag_sha}:
    get:
      summary: Get Tag
      description: '**Signature verification object**


        The response will include a `verification` object that describes the result of verifying the commit''s signature. The following fields are included in the `verification` object:


        | Name | Type | Description |

        | - | - | -- |

        | `verified` | `boolean` | Indicates whether GitHub considers the signature in this commit to be verified. |

        | `reason` | `string` | The reason for verified value. Possible values and their meanings are enumerated in table below. |

        | `signature` | `string` | The signature that was extracted from the commit. |

        | `payload` | `string` | The value that was signed. |


        These are the possible values for `reason` in the `verification` object:


        | Value | Description |

        | -- | -- |

        | `expired_key` | The key that made the signature is expired. |

        | `not_signing_key` | The "signing" flag is not among the usage flags in the GPG key that made the signature. |

        | `gpgverify_error` | There was an error communicating with the signature verification service. |

        | `gpgverify_unavailable` | The signature verification service is currently unavailable. |

        | `unsigned` | The object does not include a signature. |

        | `unknown_signature_type` | non-PGP signature was found in the commit. |

        | `no_user` | No user was associated with the `committer` email address in the commit. |

        | `unverified_email` | The `committer` email address in the commit was associated with a user, but the email address is not verified on their account. |

        | `bad_email` | The `committer` email address in the commit is not included in the identities of the PGP key that made the signature. |

        | `unknown_key` | The key that made the signature has not been registered with any user''s account. |

        | `malformed_signature` | There was an error parsing the signature. |

        | `invalid` | The signature could not be cryptographically verified using the key whose key-id was found in the signature. |

        | `valid` | None of the above errors applied, so the signature is considered to be verified. |'
      tags:
      - Tags
      operationId: getTag
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/git/tags#get-a-tag
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - name: tag_sha
        in: path
        required: true
        schema:
          type: string
      - in: header
        name: Authorization
        schema:
          type: string
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/git-tag'
              examples:
                default:
                  $ref: '#/components/examples/git-tag'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: git
        subcategory: tags
      security:
      - bearerHttpAuthentication: []
  /repos/{owner}/{repo}/releases/tags/{tag}:
    get:
      summary: Get Release By Tag Name
      description: Get published release with the specified tag.
      tags:
      - Tags
      operationId: getReleaseByTagName
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/releases/releases#get-a-release-by-tag-name
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - name: tag
        description: tag parameter
        in: path
        required: true
        schema:
          type: string
        x-multi-segment: true
      - in: header
        name: Authorization
        schema:
          type: string
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/release'
              examples:
                default:
                  $ref: '#/components/examples/release'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: releases
        subcategory: releases
      security:
      - bearerHttpAuthentication: []
  /repos/{owner}/{repo}/tags:
    get:
      summary: List Repository Tags
      description: The GitHub Repos API endpoint /repos/{owner}/{repo}/tags with the GET method retrieves a list of tags for a specified repository. Tags are references to specific points in a repository's history, typically used to mark release versions. By providing the repository owner's username and the repository name in the URL path, this endpoint returns an array of tag objects, each containing information such as the tag name, commit SHA it points to, zipball and tarball URLs for downloading the code at that tag, and a reference to the commit object. This endpoint supports pagination for repositories with many tags and requires appropriate authentication permissions to access private repositories, making it useful for developers who need to programmatically access version information or automate release-related workflows.
      tags:
      - Tags
      operationId: listRepositoryTags
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/repos/repos#list-repository-tags
      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
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/tag'
              examples:
                default:
                  $ref: '#/components/examples/tag-items'
          headers:
            Link:
              $ref: '#/components/headers/link'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: repos
        subcategory: repos
      security:
      - bearerHttpAuthentication: []
      x-api-evangelist-certified: '2025-07-16'
      x-api-naftiko-published: '2025-07-25'
  /repos/{owner}/{repo}/tags/protection:
    get:
      summary: List Tag Protection States For Repository
      description: 'This returns the tag protection states of a repository.


        This information is only available to repository administrators.'
      tags:
      - Tags
      operationId: listTagProtectionStatesForRepository
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/repos/tags#list-tag-protection-states-for-a-repository
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
      responses:
        '200':
          description: Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/tag-protection'
              examples:
                default:
                  $ref: '#/components/examples/tag-protection-items'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: repos
        subcategory: tags
      security:
      - bearerHttpAuthentication: []
    post:
      summary: Create Tag Protection State For Repository
      description: 'This creates a tag protection state for a repository.

        This endpoint is only available to repository administrators.'
      tags:
      - Tags
      operationId: createTagProtectionStateForRepository
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/repos/tags#create-a-tag-protection-state-for-a-repository
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - in: header
        name: Authorization
        schema:
          type: string
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                pattern:
                  type: string
                  description: An optional glob pattern to match against when enforcing tag protection.
              required:
              - pattern
            examples:
              default:
                value:
                  pattern: v1.*
      responses:
        '201':
          description: Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/tag-protection'
              examples:
                default:
                  $ref: '#/components/examples/tag-protection'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: repos
        subcategory: tags
      security:
      - bearerHttpAuthentication: []
  /repos/{owner}/{repo}/tags/protection/{tag_protection_id}:
    delete:
      summary: Delete Tag Protection State For Repository
      description: 'This deletes a tag protection state for a repository.

        This endpoint is only available to repository administrators.'
      tags:
      - Tags
      operationId: deleteTagProtectionStateForRepository
      externalDocs:
        description: API method documentation
        url: https://docs.github.com/enterprise-server@3.9/rest/repos/tags#delete-a-tag-protection-state-for-a-repository
      parameters:
      - $ref: '#/components/parameters/owner'
      - $ref: '#/components/parameters/repo'
      - $ref: '#/components/parameters/tag-protection-id'
      - in: header
        name: Authorization
        schema:
          type: string
      - in: header
        name: X-GitHub-Api-Version
        schema:
          type: string
          default: '2022-11-28'
      - in: header
        name: Accept
        schema:
          type: string
          default: application/vnd.github+json
      responses:
        '204':
          description: Response
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/not_found'
      x-github:
        githubCloudOnly: false
        enabledForGitHubApps: true
        category: repos
        subcategory: tags
      security:
      - bearerHttpAuthentication: []
components:
  schemas:
    nullable-simple-user:
      title: Simple User
      description: GitHub user.
      type: object
      properties:
        name:
          nullable: true
          type: string
        email:
          nullable: true
          type: string
        login:
          type: string
          example: octocat
        id:
          type: integer
          format: int64
          example: 1
        node_id:
          type: string
          example: MDQ6VXNlcjE=
        avatar_url:
          type: string
          format: uri
          example: https://github.com/images/error/octocat_happy.gif
        gravatar_id:
          type: string
          example: 41d064eb2195891e12d0413f63227ea7
          nullable: true
        url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
        html_url:
          type: string
          format: uri
          example: https://github.com/octocat
        followers_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/followers
        following_url:
          type: string
          example: https://api.github.com/users/octocat/following{/other_user}
        gists_url:
          type: string
          example: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url:
          type: string
          example: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/subscriptions
        organizations_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/orgs
        repos_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        events_url:
          type: string
          example: https://api.github.com/users/octocat/events{/privacy}
        received_events_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/received_events
        type:
          type: string
          example: User
        site_admin:
          type: boolean
        starred_at:
          type: string
          example: '"2020-07-09T00:17:55Z"'
      required:
      - avatar_url
      - events_url
      - followers_url
      - following_url
      - gists_url
      - gravatar_id
      - html_url
      - id
      - node_id
      - login
      - organizations_url
      - received_events_url
      - repos_url
      - site_admin
      - starred_url
      - subscriptions_url
      - type
      - url
      nullable: true
    basic-error:
      title: Basic Error
      description: Basic Error
      type: object
      properties:
        message:
          type: string
        documentation_url:
          type: string
        url:
          type: string
        status:
          type: string
    release:
      title: Release
      description: release.
      type: object
      properties:
        url:
          type: string
          format: uri
        html_url:
          type: string
          format: uri
        assets_url:
          type: string
          format: uri
        upload_url:
          type: string
        tarball_url:
          type: string
          format: uri
          nullable: true
        zipball_url:
          type: string
          format: uri
          nullable: true
        id:
          type: integer
        node_id:
          type: string
        tag_name:
          description: The name of the tag.
          example: v1.0.0
          type: string
        target_commitish:
          description: Specifies the commitish value that determines where the Git tag is created from.
          example: master
          type: string
        name:
          type: string
          nullable: true
        body:
          type: string
          nullable: true
        draft:
          description: true to create a draft (unpublished) release, false to create a published one.
          example: false
          type: boolean
        prerelease:
          description: Whether to identify the release as a prerelease or a full release.
          example: false
          type: boolean
        created_at:
          type: string
          format: date-time
        published_at:
          type: string
          format: date-time
          nullable: true
        author:
          $ref: '#/components/schemas/simple-user'
        assets:
          type: array
          items:
            $ref: '#/components/schemas/release-asset'
        body_html:
          type: string
        body_text:
          type: string
        mentions_count:
          type: integer
        reactions:
          $ref: '#/components/schemas/reaction-rollup'
      required:
      - assets_url
      - upload_url
      - tarball_url
      - zipball_url
      - created_at
      - published_at
      - draft
      - id
      - node_id
      - author
      - html_url
      - name
      - prerelease
      - tag_name
      - target_commitish
      - assets
      - url
    reaction-rollup:
      title: Reaction Rollup
      type: object
      properties:
        url:
          type: string
          format: uri
        total_count:
          type: integer
        '+1':
          type: integer
        '-1':
          type: integer
        laugh:
          type: integer
        confused:
          type: integer
        heart:
          type: integer
        hooray:
          type: integer
        eyes:
          type: integer
        rocket:
          type: integer
      required:
      - url
      - total_count
      - '+1'
      - '-1'
      - laugh
      - confused
      - heart
      - hooray
      - eyes
      - rocket
    release-asset:
      title: Release Asset
      description: Data related to a release.
      type: object
      properties:
        url:
          type: string
          format: uri
        browser_download_url:
          type: string
          format: uri
        id:
          type: integer
        node_id:
          type: string
        name:
          description: The file name of the asset.
          type: string
          example: Team Environment
        label:
          type: string
          nullable: true
        state:
          description: State of the release asset.
          type: string
          enum:
          - uploaded
          - open
        content_type:
          type: string
        size:
          type: integer
        download_count:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        uploader:
          $ref: '#/components/schemas/nullable-simple-user'
      required:
      - id
      - name
      - content_type
      - size
      - state
      - url
      - node_id
      - download_count
      - label
      - uploader
      - browser_download_url
      - created_at
      - updated_at
    validation-error:
      title: Validation Error
      description: Validation Error
      type: object
      required:
      - message
      - documentation_url
      properties:
        message:
          type: string
        documentation_url:
          type: string
        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
                  nullable: true
                - type: integer
                  nullable: true
                - type: array
                  nullable: true
                  items:
                    type: string
    simple-user:
      title: Simple User
      description: GitHub user.
      type: object
      properties:
        name:
          nullable: true
          type: string
        email:
          nullable: true
          type: string
        login:
          type: string
          example: octocat
        id:
          type: integer
          format: int64
          example: 1
        node_id:
          type: string
          example: MDQ6VXNlcjE=
        avatar_url:
          type: string
          format: uri
          example: https://github.com/images/error/octocat_happy.gif
        gravatar_id:
          type: string
          example: 41d064eb2195891e12d0413f63227ea7
          nullable: true
        url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat
        html_url:
          type: string
          format: uri
          example: https://github.com/octocat
        followers_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/followers
        following_url:
          type: string
          example: https://api.github.com/users/octocat/following{/other_user}
        gists_url:
          type: string
          example: https://api.github.com/users/octocat/gists{/gist_id}
        starred_url:
          type: string
          example: https://api.github.com/users/octocat/starred{/owner}{/repo}
        subscriptions_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/subscriptions
        organizations_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/orgs
        repos_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/repos
        events_url:
          type: string
          example: https://api.github.com/users/octocat/events{/privacy}
        received_events_url:
          type: string
          format: uri
          example: https://api.github.com/users/octocat/received_events
        type:
          type: string
          example: User
        site_admin:
          type: boolean
        starred_at:
          type: string
          example: '"2020-07-09T00:17:55Z"'
      required:
      - avatar_url
      - events_url
      - followers_url
      - following_url
      - gists_url
      - gravatar_id
      - html_url
      - id
      - node_id
      - login
      - organizations_url
      - received_events_url
      - repos_url
      - site_admin
      - starred_url
      - subscriptions_url
      - type
      - url
    tag:
      title: Tag
      description: Tag
      type: object
      properties:
        name:
          type: string
          example: v0.1
        commit:
          type: object
          properties:
            sha:
              type: string
            url:
              type: string
              format: uri
          required:
          - sha
          - url
        zipball_url:
          type: string
          format: uri
          example: https://github.com/octocat/Hello-World/zipball/v0.1
        tarball_url:
          type: string
          format: uri
          example: https://github.com/octocat/Hello-World/tarball/v0.1
        node_id:
          type: string
      required:
      - name
      - node_id
      - commit
      - zipball_url
      - tarball_url
    verification:
      title: Verification
      type: object
      properties:
        verified:
          type: boolean
        reason:
          type: string
        payload:
          type: string
          nullable: true
        signature:
          type: string
          nullable: true
      required:
      - verified
      - reason
      - payload
      - signature
    git-tag:
      title: Git Tag
      description: Metadata for a Git tag
      type: object
      properties:
        node_id:
          type: string
          example: MDM6VGFnOTQwYmQzMzYyNDhlZmFlMGY5ZWU1YmM3YjJkNWM5ODU4ODdiMTZhYw==
        tag:
          description: Name of the tag
          example: v0.0.1
          type: string
        sha:
          type: string
          example: 940bd336248efae0f9ee5bc7b2d5c985887b16ac
        url:
          description: URL for the tag
          example: https://api.github.com/repositories/42/git/tags/940bd336248efae0f9ee5bc7b2d5c985887b16ac
          type: string
          format: uri
        message:
          description: Message describing the purpose of the tag
          example: Initial public release
          type: string
        tagger:
          type: object
          properties:
            date:
              type: string
            email:
              type: string
            name:
              type: string
          required:
          - date
          - email
          - name
        object:
          type: object
          properties:
       

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