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