Markdown uploads API

{{< details >}}

• Tier: Free, Premium, Ultimate
• Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

{{< /details >}}

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

{{< history >}}

• Generally available in GitLab 15.10. Feature flag enforce_max_attachment_size_upload_api removed.
• full_path response attribute pattern changed in GitLab 17.1.
• id attribute introduced in GitLab 17.3.

{{< /history >}}

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 "[email protected]" "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

{{< history >}}

• Introduced in GitLab 17.2.

{{< /history >}}

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>" "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

{{< history >}}

• Introduced in GitLab 17.2.

{{< /history >}}

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>" "https://gitlab.example.com/api/v4/projects/5/uploads/1"

Download an uploaded file by secret and filename

{{< history >}}

• Introduced in GitLab 17.4.

{{< /history >}}

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>" "https://gitlab.example.com/api/v4/projects/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg"

Delete an uploaded file by ID

{{< history >}}

• Introduced in GitLab 17.2.

{{< /history >}}

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>" "https://gitlab.example.com/api/v4/projects/5/uploads/1"

Delete an uploaded file by secret and filename

{{< history >}}

• Introduced in GitLab 17.4.

{{< /history >}}

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>" "https://gitlab.example.com/api/v4/projects/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg"