Group Markdown uploads API

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

Use this API to manage Markdown uploads that can be referenced in Markdown text in epics or wiki pages.

Rate limits

The availability of this feature is controlled by a feature flag. For more information, see the history.

By default, you can upload 10,240 MB of files in a 24-hour window that starts with your first upload. Uploads to all projects and groups count toward the limit, including uploads in the UI and with the GraphQL API.

Administrators can change the limit with the markdown_upload_limit_megabytes_per_day application setting. After you reach the limit, you receive 429 Too Many Requests.

While the feature flag is disabled, uploads over the limit are logged but not blocked.

Upload a file to a group

Uploads a file to the specified group. Returns a Markdown-formatted link to the file.

You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role to use this endpoint. You cannot upload files to an archived group or a group pending deletion. The endpoint returns 403 Forbidden instead.

POST /groups/:id/uploads

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
filefileYesThe file to upload.

Example request:

shell
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "file=@/path/to/image.png" \
  --url "https://gitlab.example.com/api/v4/groups/5/uploads"

Example response:

json
{
  "id": 3,
  "alt": "image",
  "url": "/uploads/648d97c6eef5fc5df8d1004565b3ee5a/image.png",
  "full_path": "/-/group/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/image.png",
  "markdown": "![image](/uploads/648d97c6eef5fc5df8d1004565b3ee5a/image.png)"
}

List all uploads for a group

Lists all uploads for a specified group sorted by created_at in descending order.

You must have the Maintainer or Owner role to use this endpoint.

GET /groups/:id/uploads
AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.

Example request:

shell
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/5/uploads"

Example response:

json
[
  {
    "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 with the specified ID. You must have the Maintainer or Owner role to use this endpoint.

GET /groups/:id/uploads/:upload_id

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
upload_idintegerYesThe ID of the upload.

Example request:

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

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

Download an uploaded file by secret and filename

Downloads an uploaded file with the specified secret and filename. You must have the Guest, Planner, Reporter, Developer, Maintainer, or Owner role to use this endpoint.

GET /groups/:id/uploads/:secret/:filename

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
secretstringYesThe 32-character secret of the upload.
filenamestringYesThe filename of the upload.

Example request:

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

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

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/-/group/<group_id>/uploads/<secret>/<filename>. To get the API URL, replace /-/group/ with /api/v4/groups/.
  • In the raw Markdown: /uploads/<secret>/<filename>. This link does not include the project or group. If the file belongs to a project (for example, in an issue or merge request), use the project Markdown uploads API. The group endpoint returns 404 for files uploaded to a project.

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/-/group/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/sample.jpg

Use this request:

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

Delete an uploaded file by ID

Deletes an uploaded file with the specified ID. You must have the Maintainer or Owner role to use this endpoint.

DELETE /groups/:id/uploads/:upload_id

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
upload_idintegerYesThe ID of the upload.

Example request:

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

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

Delete an uploaded file by secret and filename

Deletes an uploaded file with the specified secret and filename. You must have the Maintainer or Owner role to use this endpoint.

DELETE /groups/:id/uploads/:secret/:filename

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
secretstringYesThe 32-character secret of the upload.
filenamestringYesThe filename of the upload.

Example request:

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

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