1---
2stage: Create
3group: Editor
4info: "To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments"
5type: reference, api
6---
7
8# Project wikis API **(FREE)**
9
10> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/13372) in GitLab 10.0.
11
12The project [wikis](../user/project/wiki/index.md) API is available only in APIv4.
13An API for [group wikis](group_wikis.md) is also available.
14
15## List wiki pages
16
17Get all wiki pages for a given project.
18
19```plaintext
20GET /projects/:id/wikis
21```
22
23| Attribute | Type    | Required | Description           |
24| --------- | ------- | -------- | --------------------- |
25| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
26| `with_content`      | boolean    | no      | Include pages' content  |
27
28```shell
29curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis?with_content=1"
30```
31
32Example response:
33
34```json
35[
36  {
37    "content" : "Here is an instruction how to deploy this project.",
38    "format" : "markdown",
39    "slug" : "deploy",
40    "title" : "deploy"
41  },
42  {
43    "content" : "Our development process is described here.",
44    "format" : "markdown",
45    "slug" : "development",
46    "title" : "development"
47  },{
48    "content" : "*  [Deploy](deploy)\n*  [Development](development)",
49    "format" : "markdown",
50    "slug" : "home",
51    "title" : "home"
52  }
53]
54```
55
56## Get a wiki page
57
58Get a wiki page for a given project.
59
60```plaintext
61GET /projects/:id/wikis/:slug
62```
63
64| Attribute | Type    | Required | Description           |
65| --------- | ------- | -------- | --------------------- |
66| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
67| `slug` | string  | yes       | URLencoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name`  |
68
69```shell
70curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/home"
71```
72
73Example response:
74
75```json
76{
77  "content" : "home page",
78  "format" : "markdown",
79  "slug" : "home",
80  "title" : "home"
81}
82```
83
84## Create a new wiki page
85
86Creates a new wiki page for the given repository with the given title, slug, and content.
87
88```plaintext
89POST /projects/:id/wikis
90```
91
92| Attribute     | Type    | Required | Description                  |
93| ------------- | ------- | -------- | ---------------------------- |
94| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
95| `content`       | string  | yes      | The content of the wiki page |
96| `title`        | string  | yes      | The title of the wiki page        |
97| `format` | string  | no       | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` |
98
99```shell
100curl --data "format=rdoc&title=Hello&content=Hello world" \
101     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis"
102```
103
104Example response:
105
106```json
107{
108  "content" : "Hello world",
109  "format" : "markdown",
110  "slug" : "Hello",
111  "title" : "Hello"
112}
113```
114
115## Edit an existing wiki page
116
117Updates an existing wiki page. At least one parameter is required to update the wiki page.
118
119```plaintext
120PUT /projects/:id/wikis/:slug
121```
122
123| Attribute       | Type    | Required                          | Description                      |
124| --------------- | ------- | --------------------------------- | -------------------------------  |
125| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
126| `content`       | string  | yes if `title` is not provided     | The content of the wiki page |
127| `title`        | string  | yes if `content` is not provided      | The title of the wiki page        |
128| `format` | string  | no       | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` |
129| `slug` | string  | yes       | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` |
130
131```shell
132curl --request PUT --data "format=rdoc&content=documentation&title=Docs" \
133     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo"
134```
135
136Example response:
137
138```json
139{
140  "content" : "documentation",
141  "format" : "markdown",
142  "slug" : "Docs",
143  "title" : "Docs"
144}
145```
146
147## Delete a wiki page
148
149Deletes a wiki page with a given slug.
150
151```plaintext
152DELETE /projects/:id/wikis/:slug
153```
154
155| Attribute | Type    | Required | Description           |
156| --------- | ------- | -------- | --------------------- |
157| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
158| `slug` | string  | yes       | URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name` |
159
160```shell
161curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo"
162```
163
164On success the HTTP status code is `204` and no JSON response is expected.
165
166## Upload an attachment to the wiki repository
167
168Uploads a file to the attachment folder inside the wiki's repository. The
169 attachment folder is the `uploads` folder.
170
171```plaintext
172POST /projects/:id/wikis/attachments
173```
174
175| Attribute     | Type    | Required | Description                  |
176| ------------- | ------- | -------- | ---------------------------- |
177| `id`      | integer/string    | yes      | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) |
178| `file` | string | yes | The attachment to be uploaded |
179| `branch` | string | no | The name of the branch. Defaults to the wiki repository default branch |
180
181To upload a file from your file system, use the `--form` argument. This causes
182cURL to post data using the header `Content-Type: multipart/form-data`.
183The `file=` parameter must point to a file on your file system and be preceded
184by `@`. For example:
185
186```shell
187curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
188     --form "file=@dk.png" "https://gitlab.example.com/api/v4/projects/1/wikis/attachments"
189```
190
191Example response:
192
193```json
194{
195  "file_name" : "dk.png",
196  "file_path" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png",
197  "branch" : "master",
198  "link" : {
199    "url" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png",
200    "markdown" : "![dk](uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png)"
201  }
202}
203```
204