{"meta":{"title":"REST API endpoints for Git tags","intro":"Use the REST API to interact with tag objects in your Git database on GitHub.","product":"REST API","breadcrumbs":[{"href":"/en/rest","title":"REST API"},{"href":"/en/rest/git","title":"Git database"},{"href":"/en/rest/git/tags","title":"Tags"}],"documentType":"article"},"body":"# REST API endpoints for Git tags\n\nUse the REST API to interact with tag objects in your Git database on GitHub.\n\n## About Git tags\n\nA Git tag is similar to a [Git reference](/en/rest/git/refs), but the Git commit that it points to never changes. Git tags are helpful when you want to point to specific releases. These endpoints allow you to read and write [tag objects](https://git-scm.com/book/en/v2/Git-Internals-Git-References#_tags) to your Git database on GitHub. The API only supports [annotated tag objects](https://git-scm.com/book/en/v2/Git-Internals-Git-References#_tags), not lightweight tags.\n\n> \\[!NOTE]\n> Most endpoints use `Authorization: Bearer <YOUR-TOKEN>` and `Accept: application/vnd.github+json` headers, plus `X-GitHub-Api-Version: 2026-03-10`. Curl examples below omit these standard headers for brevity.\n\n## Create a tag object\n\n```\nPOST /repos/{owner}/{repo}/git/tags\n```\n\nNote 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 the refs/tags/\\[tag] reference. If you want to create a lightweight tag, you only have to create the tag reference - this call would be unnecessary.\nSignature verification object\nThe 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:\n\nNameTypeDescriptionverifiedbooleanIndicates whether GitHub considers the signature in this commit to be verified.reasonstringThe reason for verified value. Possible values and their meanings are enumerated in table below\\.signaturestringThe signature that was extracted from the commit.payloadstringThe value that was signed.verified\\_atstringThe date the signature was verified by GitHub.\nThese are the possible values for reason in the verification object:\n\nValueDescriptionexpired\\_keyThe key that made the signature is expired.not\\_signing\\_keyThe \"signing\" flag is not among the usage flags in the GPG key that made the signature.gpgverify\\_errorThere was an error communicating with the signature verification service.gpgverify\\_unavailableThe signature verification service is currently unavailable.unsignedThe object does not include a signature.unknown\\_signature\\_typeA non-PGP signature was found in the commit.no\\_userNo user was associated with the committer email address in the commit.unverified\\_emailThe committer email address in the commit was associated with a user, but the email address is not verified on their account.bad\\_emailThe committer email address in the commit is not included in the identities of the PGP key that made the signature.unknown\\_keyThe key that made the signature has not been registered with any user's account.malformed\\_signatureThere was an error parsing the signature.invalidThe signature could not be cryptographically verified using the key whose key-id was found in the signature.validNone of the above errors applied, so the signature is considered to be verified.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`owner`** (string) (required)\n  The account owner of the repository. The name is not case sensitive.\n\n* **`repo`** (string) (required)\n  The name of the repository without the .git extension. The name is not case sensitive.\n\n#### Body parameters\n\n* **`tag`** (string) (required)\n  The tag's name. This is typically a version (e.g., \"v0.0.1\").\n\n* **`message`** (string) (required)\n  The tag message.\n\n* **`object`** (string) (required)\n  The SHA of the git object this is tagging.\n\n* **`type`** (string) (required)\n  The type of the object we're tagging. Normally this is a commit but it can also be a tree or a blob.\n  Can be one of: `commit`, `tree`, `blob`\n\n* **`tagger`** (object)\n  An object with information about the individual creating the tag.\n  * **`name`** (string) (required)\n    The name of the author of the tag\n  * **`email`** (string) (required)\n    The email of the author of the tag\n  * **`date`** (string)\n    When this object was tagged. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.\n\n### HTTP response status codes\n\n* **201** - Created\n\n* **409** - Conflict\n\n* **422** - Validation failed, or the endpoint has been spammed.\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X POST \\\n  https://api.github.com/repos/OWNER/REPO/git/tags \\\n  -d '{\n  \"tag\": \"v0.0.1\",\n  \"message\": \"initial version\",\n  \"object\": \"c3d0be41ecbe669545ee3e94d31ed9a4bc91ee3c\",\n  \"type\": \"commit\",\n  \"tagger\": {\n    \"name\": \"Monalisa Octocat\",\n    \"email\": \"octocat@github.com\",\n    \"date\": \"2011-06-17T14:53:35-07:00\"\n  }\n}'\n```\n\n**Response schema (Status: 201):**\n\n* `node_id`: required, string\n* `tag`: required, string\n* `sha`: required, string\n* `url`: required, string, format: uri\n* `message`: required, string\n* `tagger`: required, object:\n  * `date`: required, string\n  * `email`: required, string\n  * `name`: required, string\n* `object`: required, object:\n  * `sha`: required, string\n  * `type`: required, string\n  * `url`: required, string, format: uri\n* `verification`: `Verification`:\n  * `verified`: required, boolean\n  * `reason`: required, string\n  * `payload`: required, string or null\n  * `signature`: required, string or null\n  * `verified_at`: required, string or null\n\n## Get a tag\n\n```\nGET /repos/{owner}/{repo}/git/tags/{tag_sha}\n```\n\nSignature verification object\nThe 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:\n\nNameTypeDescriptionverifiedbooleanIndicates whether GitHub considers the signature in this commit to be verified.reasonstringThe reason for verified value. Possible values and their meanings are enumerated in table below\\.signaturestringThe signature that was extracted from the commit.payloadstringThe value that was signed.verified\\_atstringThe date the signature was verified by GitHub.\nThese are the possible values for reason in the verification object:\n\nValueDescriptionexpired\\_keyThe key that made the signature is expired.not\\_signing\\_keyThe \"signing\" flag is not among the usage flags in the GPG key that made the signature.gpgverify\\_errorThere was an error communicating with the signature verification service.gpgverify\\_unavailableThe signature verification service is currently unavailable.unsignedThe object does not include a signature.unknown\\_signature\\_typeA non-PGP signature was found in the commit.no\\_userNo user was associated with the committer email address in the commit.unverified\\_emailThe committer email address in the commit was associated with a user, but the email address is not verified on their account.bad\\_emailThe committer email address in the commit is not included in the identities of the PGP key that made the signature.unknown\\_keyThe key that made the signature has not been registered with any user's account.malformed\\_signatureThere was an error parsing the signature.invalidThe signature could not be cryptographically verified using the key whose key-id was found in the signature.validNone of the above errors applied, so the signature is considered to be verified.\n\n### Parameters\n\n#### Headers\n\n* **`accept`** (string)\n  Setting to `application/vnd.github+json` is recommended.\n\n#### Path and query parameters\n\n* **`owner`** (string) (required)\n  The account owner of the repository. The name is not case sensitive.\n\n* **`repo`** (string) (required)\n  The name of the repository without the .git extension. The name is not case sensitive.\n\n* **`tag_sha`** (string) (required)\n\n### HTTP response status codes\n\n* **200** - OK\n\n* **404** - Resource not found\n\n* **409** - Conflict\n\n### Code examples\n\n#### Example\n\n**Request:**\n\n```curl\ncurl -L \\\n  -X GET \\\n  https://api.github.com/repos/OWNER/REPO/git/tags/TAG_SHA\n```\n\n**Response schema (Status: 200):**\n\nSame response schema as [Create a tag object](#create-a-tag-object)."}