Markdown uploads API

Use this API to manage Markdown uploads that can be referenced in Markdown text in issues, merge requests, snippets, or wiki pages.

Create an upload

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:

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" \
    --url "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": "![dk](/uploads/66dbcd21ec5d24ed6ea225176098d52b/dk.png)"
}

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 in markdown is used.

List uploads

Lists all uploads of a project sorted by created_at in descending order.

Prerequisites:

• the Maintainer or Owner role.

GET /projects/:id/uploads

Supported attributes:

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "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

Downloads an uploaded file by ID.

Prerequisites:

• the Maintainer or Owner role.

GET /projects/:id/uploads/:upload_id

Supported attributes:

If successful, returns 200 and the uploaded file in the response body.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "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:

• the Guest, Planner, Reporter, Developer, Maintainer, or Owner role.

GET /projects/:id/uploads/:secret/:filename

Supported attributes:

If successful, returns 200 and the uploaded file in the response body.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg"

Download a file linked from a description or comment

To download a file that is linked from a description or comment, get the secret and filename from the link. The link to an uploaded file has one of these formats:

• On the rendered page: https://gitlab.example.com/-/project/<project_id>/uploads/<secret>/<filename>. To get the API URL, replace /-/project/ with /api/v4/projects/.
• In the raw Markdown: /uploads/<secret>/<filename>. This link does not include the project or group. If the file belongs to a group (for example, in an epic), use the group Markdown uploads API. The project endpoint returns 404 for files uploaded to a group.

Copy the filename from the link, not from your original file. GitLab can change the filename when the file is uploaded. For example, GitLab replaces spaces with underscores.

For example, for this link on a rendered page:

https://gitlab.example.com/-/project/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg

Use this request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg"

Delete an uploaded file by ID

Deletes an uploaded file by ID.

Prerequisites:

• the Maintainer or Owner role.

DELETE /projects/:id/uploads/:upload_id

Supported attributes:

If successful, returns 204 status code without any response body.

Example request:

curl --request DELETE \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/uploads/1"

Delete an uploaded file by secret and filename

Deletes an uploaded file by secret and filename.

Prerequisites:

• the Maintainer or Owner role.

DELETE /projects/:id/uploads/:secret/:filename

Supported attributes:

If successful, returns 204 status code without any response body.

Example request:

curl --request DELETE \
    --header "PRIVATE-TOKEN: <your_access_token>" \
    --url "https://gitlab.example.com/api/v4/projects/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg"