Project wikis API

  • The encoding field was added in GitLab 14.9.
  • The render_html attribute was added in GitLab 14.9.
  • The version attribute was added in GitLab 14.9.

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.

GET /projects/:id/wikis
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
with_contentbooleannoInclude pages’ content
curl --header "PRIVATE-TOKEN: <your_access_token>" "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"
  }
]

Get a wiki page

Get a wiki page for a given project.

GET /projects/:id/wikis/:slug
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
slugstringyesURL encoded slug (a unique string) of the wiki page, such as dir%2Fpage_name
render_htmlbooleannoReturn the rendered HTML of the wiki page
versionstringnoWiki page version SHA
curl --header "PRIVATE-TOKEN: <your_access_token>" "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 new wiki page

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

POST /projects/:id/wikis
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
contentstringyesThe content of the wiki page
titlestringyesThe title of the wiki page
formatstringnoThe 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>" "https://gitlab.example.com/api/v4/projects/1/wikis"

Example response:

{
  "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.

PUT /projects/:id/wikis/:slug
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
contentstringyes if title is not providedThe content of the wiki page
titlestringyes if content is not providedThe title of the wiki page
formatstringnoThe format of the wiki page. Available formats are: markdown (default), rdoc, asciidoc and org
slugstringyesURL-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>" "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 wiki page with a given slug.

DELETE /projects/:id/wikis/:slug
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
slugstringyesURL-encoded slug (a unique string) of the wiki page, such as dir%2Fpage_name 
curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis/foo"

On success the HTTP status code is 204 and no JSON response 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
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
filestringyesThe attachment to be uploaded
branchstringnoThe 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" "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" : "![dk](uploads/6a061c4cf9f1c28cb22c384b4b8d4e3c/dk.png)"
  }
}