Markdown uploads API
- Tier: Free, Premium, Ultimate
- Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Markdown uploads are files uploaded to a project that can be referenced in Markdown text in an issue, merge request, snippet, or wiki page.
Upload a file
Uploads a file to the specified project to be used in an issue or merge request description, or a comment.
POST /projects/:id/uploads
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
file | string | Yes | File to be uploaded. |
id | integer or string | Yes | ID or URL-encoded path of the project. |
To upload a file from your file system, use the --form
argument. This causes cURL to post data using the
Content-Type: multipart/form-data
header. The file=
parameter must point to a file on your file system and be
preceded by @
.
Example request:
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/5/uploads"
Example response:
{
"id": 5,
"alt": "dk",
"url": "/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png",
"full_path": "/-/project/1234/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png",
"markdown": ""
}
In the response, the:
full_path
is the absolute path to the file.url
can be used in Markdown contexts. The link is expanded when the format inmarkdown
is used.
List uploads
Get all uploads of the project sorted by created_at
in descending order.
Prerequisites:
- At least the Maintainer role.
GET /projects/:id/uploads
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/uploads"
Example response:
[
{
"id": 1,
"size": 1024,
"filename": "image.png",
"created_at":"2024-06-20T15:53:03.067Z",
"uploaded_by": {
"id": 18,
"name" : "Alexandra Bashirian",
"username" : "eileen.lowe"
}
},
{
"id": 2,
"size": 512,
"filename": "other-image.png",
"created_at":"2024-06-19T15:53:03.067Z",
"uploaded_by": null
}
]
Download an uploaded file by ID
Download an uploaded file by ID.
Prerequisites:
- At least the Maintainer role.
GET /projects/:id/uploads/:upload_id
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project. |
upload_id | integer | Yes | ID of the upload. |
If successful, returns 200
and the uploaded file in the response body.
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/uploads/1"
Download an uploaded file by secret and filename
Download an uploaded file by secret and filename.
Prerequisites:
- At least the Guest role.
GET /projects/:id/uploads/:secret/:filename
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project. |
secret | string | Yes | 32-character secret of the upload. |
filename | string | Yes | Filename of the upload. |
If successful, returns 200
and the uploaded file in the response body.
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg"
Delete an uploaded file by ID
Delete an uploaded file by ID.
Prerequisites:
- At least the Maintainer role.
DELETE /projects/:id/uploads/:upload_id
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project. |
upload_id | integer | Yes | ID of the upload. |
If successful, returns 204
status code without any response body.
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/uploads/1"
Delete an uploaded file by secret and filename
Delete an uploaded file by secret and filename.
Prerequisites:
- At least the Maintainer role.
DELETE /projects/:id/uploads/:secret/:filename
Supported attributes:
Attribute | Type | Required | Description |
---|---|---|---|
id | integer or string | Yes | ID or URL-encoded path of the project. |
secret | string | Yes | 32-character secret of the upload. |
filename | string | Yes | Filename of the upload. |
If successful, returns 204
status code without any response body.
Example request:
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg"
Docs
Edit this page to fix an error or add an improvement in a merge request.
Create an issue to suggest an improvement to this page.
Product
Create an issue if there's something you don't like about this feature.
Propose functionality by submitting a feature request.
Feature availability and product trials
View pricing to see all GitLab tiers and features, or to upgrade.
Try GitLab for free with access to all features for 30 days.
Get help
If you didn't find what you were looking for, search the docs.
If you want help with something specific and could use community support, post on the GitLab forum.
For problems setting up or using this feature (depending on your GitLab subscription).
Request support