Project wikis API

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

The project wikis API is available only in APIv4. An API for group wikis is also available.

List wiki pages

Get all wiki pages for a given project.

Copy to clipboard
GET /projects/:id/wikis
Attribute Type Required Description
id integer/string Yes The ID or URL-encoded path of the project.
with_content boolean No Include pages’ content.
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis?with_content=1"

Example response:

Copy to clipboard
[
  {
    "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"
  }
]

Get a wiki page

Get a wiki page for a given project.

Copy to clipboard
GET /projects/:id/wikis/:slug
Attribute Type Required Description
id integer/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.
Copy to clipboard
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/home"

Example response:

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

Create a new wiki page

Creates a new wiki page for the given repository with the given title, slug, and content.

Copy to clipboard
POST /projects/:id/wikis
Attribute Type Required Description
id integer/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.
Copy to clipboard
curl --data "format=rdoc&title=Hello&content=Hello world" \
     --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis"

Example response:

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

Edit an existing wiki page

Updates an existing wiki page. At least one parameter is required to update the wiki page.

Copy to clipboard
PUT /projects/:id/wikis/:slug
Attribute Type Required Description
id integer/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.
Copy to clipboard
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"

Example response:

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

Delete a wiki page

Deletes a wiki page with a given slug.

Copy to clipboard
DELETE /projects/:id/wikis/:slug
Attribute Type Required Description
id integer/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.
Copy to clipboard
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "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.

Copy to clipboard
POST /projects/:id/wikis/attachments
Attribute Type Required Description
id integer/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:

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

Example response:

Copy to clipboard
{
  "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)"
  }
}