2020-06-17 03:08:38 +00:00
---
stage: Release
2020-12-01 15:09:28 +00:00
group: Release
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-06-17 03:08:38 +00:00
---
2019-01-11 07:43:43 +00:00
# Release links API
2020-05-21 06:08:25 +00:00
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/41766) in GitLab 11.7.
2019-01-11 07:43:43 +00:00
2020-12-16 00:09:58 +00:00
Using this API you can manipulate GitLab [Release ](../../user/project/releases/index.md ) links. For manipulating other Release assets, see [Release API ](index.md ).
2020-04-08 06:09:54 +00:00
GitLab supports links to `http` , `https` , and `ftp` assets.
2019-01-11 07:43:43 +00:00
## Get links
Get assets as links from a Release.
2020-02-29 03:07:51 +00:00
```plaintext
2019-01-11 07:43:43 +00:00
GET /projects/:id/releases/:tag_name/assets/links
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | --------------------------------------- |
2019-03-25 04:56:57 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../README.md#namespaced-path-encoding ). |
2019-01-11 07:43:43 +00:00
| `tag_name` | string | yes | The tag associated with the Release. |
Example request:
2020-01-30 15:09:15 +00:00
```shell
2021-01-11 06:10:29 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links"
2019-01-11 07:43:43 +00:00
```
Example response:
```json
[
{
"id":2,
"name":"awesome-v0.2.msi",
"url":"http://192.168.10.15:3000/msi",
2020-06-03 18:08:28 +00:00
"external":true,
"link_type":"other"
2019-01-11 07:43:43 +00:00
},
{
"id":1,
"name":"awesome-v0.2.dmg",
"url":"http://192.168.10.15:3000",
2020-06-03 18:08:28 +00:00
"external":true,
"link_type":"other"
2019-01-11 07:43:43 +00:00
}
]
```
## Get a link
Get an asset as a link from a Release.
2020-02-29 03:07:51 +00:00
```plaintext
2019-01-11 07:43:43 +00:00
GET /projects/:id/releases/:tag_name/assets/links/:link_id
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | --------------------------------------- |
2019-03-25 04:56:57 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../README.md#namespaced-path-encoding ). |
2019-01-11 07:43:43 +00:00
| `tag_name` | string | yes | The tag associated with the Release. |
2020-05-07 06:09:38 +00:00
| `link_id` | integer | yes | The ID of the link. |
2019-01-11 07:43:43 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2021-01-11 06:10:29 +00:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"
2019-01-11 07:43:43 +00:00
```
Example response:
```json
{
"id":1,
"name":"awesome-v0.2.dmg",
"url":"http://192.168.10.15:3000",
2020-06-03 18:08:28 +00:00
"external":true,
"link_type":"other"
2019-01-11 07:43:43 +00:00
}
```
## Create a link
Create an asset as a link from a Release.
2020-02-29 03:07:51 +00:00
```plaintext
2019-01-11 07:43:43 +00:00
POST /projects/:id/releases/:tag_name/assets/links
```
2020-11-26 06:09:20 +00:00
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../README.md#namespaced-path-encoding ). |
| `tag_name` | string | yes | The tag associated with the Release. |
| `name` | string | yes | The name of the link. Link names must be unique within the release. |
| `url` | string | yes | The URL of the link. Link URLs must be unique within the release. |
| `filepath` | string | no | Optional path for a [Direct Asset link ](../../user/project/releases/index.md#permanent-links-to-release-assets ). |
| `link_type` | string | no | The type of the link: `other` , `runbook` , `image` , `package` . Defaults to `other` . |
2019-01-11 07:43:43 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2019-01-11 07:43:43 +00:00
curl --request POST \
2021-01-11 06:10:29 +00:00
--header "PRIVATE-TOKEN: < your_access_token > " \
2020-11-06 18:09:07 +00:00
--data name="hellodarwin-amd64" \
--data url="https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64" \
--data filepath="/bin/hellodarwin-amd64" \
"https://gitlab.example.com/api/v4/projects/20/releases/v1.7.0/assets/links"
2019-01-11 07:43:43 +00:00
```
Example response:
```json
{
2020-11-06 18:09:07 +00:00
"id":2,
"name":"hellodarwin-amd64",
"url":"https://gitlab.example.com/mynamespace/hello/-/jobs/688/artifacts/raw/bin/hello-darwin-amd64",
"direct_asset_url":"https://gitlab.example.com/mynamespace/hello/-/releases/v1.7.0/downloads/bin/hellodarwin-amd64",
"external":false,
2020-06-03 18:08:28 +00:00
"link_type":"other"
2019-01-11 07:43:43 +00:00
}
```
## Update a link
Update an asset as a link from a Release.
2020-02-29 03:07:51 +00:00
```plaintext
2019-01-11 07:43:43 +00:00
PUT /projects/:id/releases/:tag_name/assets/links/:link_id
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | --------------------------------------- |
2019-03-25 04:56:57 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../README.md#namespaced-path-encoding ). |
2019-01-11 07:43:43 +00:00
| `tag_name` | string | yes | The tag associated with the Release. |
2020-06-03 18:08:28 +00:00
| `link_id` | integer | yes | The ID of the link. |
2019-01-11 07:43:43 +00:00
| `name` | string | no | The name of the link. |
2020-06-03 18:08:28 +00:00
| `url` | string | no | The URL of the link. |
2020-11-06 18:09:07 +00:00
| `filepath` | string | no | Optional path for a [Direct Asset link ](../../user/project/releases/index.md#permanent-links-to-release-assets ).
2020-06-03 18:08:28 +00:00
| `link_type` | string | no | The type of the link: `other` , `runbook` , `image` , `package` . Defaults to `other` . |
2019-01-11 07:43:43 +00:00
2020-12-04 21:09:29 +00:00
NOTE:
2019-01-11 07:43:43 +00:00
You have to specify at least one of `name` or `url`
Example request:
2020-01-30 15:09:15 +00:00
```shell
2021-01-11 06:10:29 +00:00
curl --request PUT --data name="new name" --data link_type="runbook" --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"
2019-01-11 07:43:43 +00:00
```
Example response:
```json
{
"id":1,
"name":"new name",
"url":"http://192.168.10.15:3000",
2020-06-03 18:08:28 +00:00
"external":true,
"link_type":"runbook"
2019-01-11 07:43:43 +00:00
}
```
## Delete a link
Delete an asset as a link from a Release.
2020-02-29 03:07:51 +00:00
```plaintext
2019-01-11 07:43:43 +00:00
DELETE /projects/:id/releases/:tag_name/assets/links/:link_id
```
| Attribute | Type | Required | Description |
| ------------- | -------------- | -------- | --------------------------------------- |
2019-03-25 04:56:57 +00:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](../README.md#namespaced-path-encoding ). |
2019-01-11 07:43:43 +00:00
| `tag_name` | string | yes | The tag associated with the Release. |
2020-05-07 06:09:38 +00:00
| `link_id` | integer | yes | The ID of the link. |
2019-01-11 07:43:43 +00:00
Example request:
2020-01-30 15:09:15 +00:00
```shell
2021-01-11 06:10:29 +00:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/24/releases/v0.1/assets/links/1"
2019-01-11 07:43:43 +00:00
```
Example response:
```json
{
"id":1,
"name":"new name",
"url":"http://192.168.10.15:3000",
2020-06-03 18:08:28 +00:00
"external":true,
"link_type":"other"
2019-01-11 07:43:43 +00:00
}
```