Project wikis API

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

Use this API to manage project wikis. An API for group wikis is also available.

Comments on a wiki page are called notes. To interact with them, use the notes API.

List all wiki pages

Lists all wiki pages for a specified project.

GET /projects/:id/wikis

Attribute	Type	Required	Description
`id`	integer or string	Yes	The ID or URL-encoded path of the project.
`with_content`	boolean	No	Include pages’ content.

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/wikis?with_content=1"

Example response:

[
  {
    "content" : "Here is an instruction how to deploy this project.",
    "format" : "markdown",
    "slug" : "deploy",
    "title" : "deploy",
    "encoding": "UTF-8"
  },
  {
    "content" : "Our development process is described here.",
    "format" : "markdown",
    "slug" : "development",
    "title" : "development",
    "encoding": "UTF-8"
  },{
    "content" : "*  [Deploy](deploy)\n*  [Development](development)",
    "format" : "markdown",
    "slug" : "home",
    "title" : "home",
    "encoding": "UTF-8"
  }
]

Retrieve a wiki page

Retrieves a specified wiki page for a project.

GET /projects/:id/wikis/:slug

Attribute	Type	Required	Description
`id`	integer or string	Yes	The ID or URL-encoded path of the project.
`slug`	string	Yes	URL encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name`.
`render_html`	boolean	No	Return the rendered HTML of the wiki page.
`version`	string	No	Wiki page version SHA.

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/wikis/home"

Example response:

{
  "content" : "home page",
  "format" : "markdown",
  "slug" : "home",
  "title" : "home",
  "encoding": "UTF-8"
}

Create a wiki page

Creates a wiki page for a specified project with the given title, slug, and content.

POST /projects/:id/wikis

Attribute	Type	Required	Description
`id`	integer or string	Yes	The ID or URL-encoded path of the project.
`content`	string	Yes	The content of the wiki page.
`title`	string	Yes	The title of the wiki page.
`format`	string	No	The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc`, and `org`.

curl --data "format=rdoc&title=Hello&content=Hello world" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/wikis"

Example response:

{
  "content" : "Hello world",
  "format" : "markdown",
  "slug" : "Hello",
  "title" : "Hello",
  "encoding": "UTF-8"
}

For Markdown content with special characters and diagrams, use --data-urlencode with a file reference to handle encoding automatically.

For example, create a file named content.md with your wiki content, then run:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data-urlencode "title=Page with Complex Content" \
  --data-urlencode "content@content.md" \
  --url "https://gitlab.example.com/api/v4/projects/1/wikis"

The --data-urlencode "content@content.md" option URL-encodes the contents of the Markdown file and assigns it to the content attribute. This encoding handles special characters, line breaks, and complex Markdown syntax that might otherwise cause errors.

Example response:

{
"content": "<contents of content.md>",
"format": "markdown",
"slug": "Page-with-Complex-Content",
"title": "Page with Complex Content",
"encoding": "UTF-8"
}

Update a wiki page

Updates a specified wiki page. At least one parameter is required to update the wiki page.

PUT /projects/:id/wikis/:slug

Attribute	Type	Required	Description
`id`	integer or string	Yes	The ID or URL-encoded path of the project.
`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.
`format`	string	No	The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc`, and `org`.
`slug`	string	Yes	URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name`.

curl --request PUT \
  --data "format=rdoc&content=documentation&title=Docs" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/wikis/foo"

Example response:

{
  "content" : "documentation",
  "format" : "markdown",
  "slug" : "Docs",
  "title" : "Docs",
  "encoding": "UTF-8"
}

Delete a wiki page

Deletes a specified wiki page.

DELETE /projects/:id/wikis/:slug

Attribute	Type	Required	Description
`id`	integer or string	Yes	The ID or URL-encoded path of the project.
`slug`	string	Yes	URL-encoded slug (a unique string) of the wiki page, such as `dir%2Fpage_name`.

curl --request DELETE \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/wikis/foo"

If successful, a 204 No Content HTTP response with an empty body is expected.

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.

POST /projects/:id/wikis/attachments

Attribute	Type	Required	Description
`id`	integer or string	Yes	The ID or URL-encoded path of the project.
`file`	string	Yes	The attachment to be uploaded.
`branch`	string	No	The name of the branch. Defaults to the wiki repository default branch.

To upload a file from your file system, use the --form argument. This causes cURL to post data using the header Content-Type: multipart/form-data. The file= parameter must point to a file on your file system and be preceded by @. For example:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "file=@dk.png" \
  --url "https://gitlab.example.com/api/v4/projects/1/wikis/attachments"

Example response:

{
  "file_name" : "dk.png",
  "file_path" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png",
  "branch" : "main",
  "link" : {
    "url" : "uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png",
    "markdown" : "![A description of the attachment](uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png)"
  }
}