2020-07-30 08:09:33 -04:00
---
stage: Create
2021-02-04 13:09:22 -05:00
group: Editor
2022-09-21 17:13:33 -04:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-07-30 08:09:33 -04:00
---
2021-02-19 13:10:51 -05:00
# Project wikis API **(FREE)**
2017-09-06 18:21:52 -04:00
2022-03-08 10:15:55 -05:00
> - The `encoding` field was [added](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/81150) in GitLab 14.9.
> - The `render_html` attribute was [added](https://gitlab.com/gitlab-org/gitlab/-/issues/336792) in GitLab 14.9.
2022-03-16 17:09:14 -04:00
> - The `version` attribute was [added](https://gitlab.com/gitlab-org/gitlab/-/issues/336792) in GitLab 14.9.
2022-02-24 13:19:04 -05:00
2021-03-31 17:09:15 -04:00
The project [wikis ](../user/project/wiki/index.md ) API is available only in APIv4.
An API for [group wikis ](group_wikis.md ) is also available.
2017-09-06 18:21:52 -04:00
## List wiki pages
Get all wiki pages for a given project.
2020-02-28 22:07:51 -05:00
```plaintext
2017-09-06 18:21:52 -04:00
GET /projects/:id/wikis
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2017-09-06 18:21:52 -04:00
| `with_content` | boolean | no | Include pages' content |
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/wikis?with_content=1"
2017-09-06 18:21:52 -04:00
```
Example response:
```json
[
{
"content" : "Here is an instruction how to deploy this project.",
"format" : "markdown",
"slug" : "deploy",
2022-02-24 13:19:04 -05:00
"title" : "deploy",
"encoding": "UTF-8"
2017-09-06 18:21:52 -04:00
},
{
"content" : "Our development process is described here.",
"format" : "markdown",
"slug" : "development",
2022-02-24 13:19:04 -05:00
"title" : "development",
"encoding": "UTF-8"
2017-09-06 18:21:52 -04:00
},{
"content" : "* [Deploy ](deploy )\n* [Development ](development )",
"format" : "markdown",
"slug" : "home",
2022-02-24 13:19:04 -05:00
"title" : "home",
"encoding": "UTF-8"
2017-09-06 18:21:52 -04:00
}
]
```
## Get a wiki page
Get a wiki page for a given project.
2020-02-28 22:07:51 -05:00
```plaintext
2017-09-06 18:21:52 -04:00
GET /projects/:id/wikis/:slug
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2022-05-12 05:08:08 -04:00
| `slug` | string | yes | URL encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` |
2022-03-08 10:15:55 -05:00
| `render_html` | boolean | no | Return the rendered HTML of the wiki page |
2022-05-20 11:09:10 -04:00
| `version` | string | no | Wiki page version SHA |
2017-09-06 18:21:52 -04:00
2020-01-30 10:09:15 -05:00
```shell
2020-05-27 20:08:37 -04:00
curl --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/wikis/home"
2017-09-06 18:21:52 -04:00
```
Example response:
```json
2018-11-21 02:33:49 -05:00
{
"content" : "home page",
"format" : "markdown",
"slug" : "home",
2022-02-24 13:19:04 -05:00
"title" : "home",
"encoding": "UTF-8"
2018-11-21 02:33:49 -05:00
}
2017-09-06 18:21:52 -04:00
```
## Create a new wiki page
Creates a new wiki page for the given repository with the given title, slug, and content.
2020-02-28 22:07:51 -05:00
```plaintext
2017-09-06 18:21:52 -04:00
POST /projects/:id/wikis
```
| Attribute | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2017-09-06 18:21:52 -04:00
| `content` | string | yes | The content of the wiki page |
| `title` | string | yes | The title of the wiki page |
2020-01-15 22:08:47 -05:00
| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc` , `asciidoc` and `org` |
2017-09-06 18:21:52 -04:00
2020-01-30 10:09:15 -05:00
```shell
2021-06-02 11:09:59 -04:00
curl --data "format=rdoc& title=Hello& content=Hello world" \
--header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/wikis"
2017-09-06 18:21:52 -04:00
```
Example response:
```json
2018-09-04 06:39:08 -04:00
{
2017-09-06 18:21:52 -04:00
"content" : "Hello world",
"format" : "markdown",
"slug" : "Hello",
2022-02-24 13:19:04 -05:00
"title" : "Hello",
"encoding": "UTF-8"
2018-09-04 06:39:08 -04:00
}
2017-09-06 18:21:52 -04:00
```
## Edit an existing wiki page
Updates an existing wiki page. At least one parameter is required to update the wiki page.
2020-02-28 22:07:51 -05:00
```plaintext
2017-09-06 18:21:52 -04:00
PUT /projects/:id/wikis/:slug
```
| Attribute | Type | Required | Description |
| --------------- | ------- | --------------------------------- | ------------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2017-09-06 18:21:52 -04:00
| `content` | string | yes if `title` is not provided | The content of the wiki page |
| `title` | string | yes if `content` is not provided | The title of the wiki page |
2020-01-15 22:08:47 -05:00
| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc` , `asciidoc` and `org` |
2021-06-01 11:09:52 -04:00
| `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` |
2017-09-06 18:21:52 -04:00
2020-01-30 10:09:15 -05:00
```shell
2021-06-02 11:09:59 -04:00
curl --request PUT --data "format=rdoc& content=documentation& title=Docs" \
--header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/wikis/foo"
2017-09-06 18:21:52 -04:00
```
Example response:
```json
{
"content" : "documentation",
"format" : "markdown",
"slug" : "Docs",
2022-02-24 13:19:04 -05:00
"title" : "Docs",
"encoding": "UTF-8"
2017-09-06 18:21:52 -04:00
}
```
## Delete a wiki page
Deletes a wiki page with a given slug.
2020-02-28 22:07:51 -05:00
```plaintext
2017-09-06 18:21:52 -04:00
DELETE /projects/:id/wikis/:slug
```
| Attribute | Type | Required | Description |
| --------- | ------- | -------- | --------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2021-06-01 11:09:52 -04:00
| `slug` | string | yes | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` |
2017-09-06 18:21:52 -04:00
2020-01-30 10:09:15 -05:00
```shell
2018-12-27 04:03:08 -05:00
curl --request DELETE --header "PRIVATE-TOKEN: < your_access_token > " "https://gitlab.example.com/api/v4/projects/1/wikis/foo"
2017-09-06 18:21:52 -04:00
```
2018-09-04 06:39:08 -04:00
On success the HTTP status code is `204` and no JSON response is expected.
2017-09-15 07:27:57 -04:00
2018-09-04 06:39:08 -04:00
## Upload an attachment to the wiki repository
Uploads a file to the attachment folder inside the wiki's repository. The
attachment folder is the `uploads` folder.
2020-02-28 22:07:51 -05:00
```plaintext
2018-09-04 06:39:08 -04:00
POST /projects/:id/wikis/attachments
```
| Attribute | Type | Required | Description |
| ------------- | ------- | -------- | ---------------------------- |
2021-06-28 11:08:03 -04:00
| `id` | integer/string | yes | The ID or [URL-encoded path of the project ](index.md#namespaced-path-encoding ) |
2018-09-04 06:39:08 -04:00
| `file` | string | yes | The attachment to be uploaded |
| `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch |
2021-02-04 04:09:30 -05:00
To upload a file from your file system, use the `--form` argument. This causes
2018-09-04 06:39:08 -04:00
cURL to post data using the header `Content-Type: multipart/form-data` .
2021-02-04 04:09:30 -05:00
The `file=` parameter must point to a file on your file system and be preceded
2018-09-04 06:39:08 -04:00
by `@` . For example:
2020-01-30 10:09:15 -05:00
```shell
2021-06-02 11:09:59 -04:00
curl --request POST --header "PRIVATE-TOKEN: < your_access_token > " \
--form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/1/wikis/attachments"
2018-09-04 06:39:08 -04:00
```
Example response:
```json
{
"file_name" : "dk.png",
"file_path" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png",
"branch" : "master",
"link" : {
"url" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png",
"markdown" : "![dk](uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png)"
}
}
```