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/uploadsSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the group. |
file | file | Yes | The file to upload. |
Example request:
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:
{
"id": 3,
"alt": "image",
"url": "/uploads/648d97c6eef5fc5df8d1004565b3ee5a/image.png",
"full_path": "/-/group/5/uploads/648d97c6eef5fc5df8d1004565b3ee5a/image.png",
"markdown": ""
}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| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the group. |
Example request:
curl --header "PRIVATE-TOKEN: <your_access_token>" \
--url "https://gitlab.example.com/api/v4/groups/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 with the specified ID. You must have the Maintainer or Owner role to use this endpoint.
GET /groups/:id/uploads/:upload_idSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the group. |
upload_id | integer | Yes | The ID of the upload. |
Example request:
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/:filenameSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the group. |
secret | string | Yes | The 32-character secret of the upload. |
filename | string | Yes | The filename of the upload. |
Example request:
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 returns404for 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.jpgUse this request:
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_idSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the group. |
upload_id | integer | Yes | The ID of the upload. |
Example request:
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/:filenameSupported attributes:
| Attribute | Type | Required | Description |
|---|---|---|---|
id | integer or string | Yes | The ID or URL-encoded path of the group. |
secret | string | Yes | The 32-character secret of the upload. |
filename | string | Yes | The filename of the upload. |
Example request:
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.