Skip to main content

Using the REST API

How to use the API

You can access the application programming interface (API) using HTTPS GET and POST requests. There are many tools that enable you to make these requests. For this documentation, we will use curl (a tool to transfer data from or to a server) in a Unix-like environment.

Base URL

All API requests use the same base URL:

This URL will prefix all requests.

Valid API request

The following is a basic example of a request to

curl ""

Example response:


Add the --include option to show server response headers and give useful debugging output.


All API requests require authentication to return data. There are several ways you can authenticate with the API:

  • Personal access token (PAT)
  • Project access token
  • Group access token
  • Pipeline trigger token (limited endpoints only)

If the authentication information is not valid or is missing, returns an error message with a status code of 401:

"message": "401 Unauthorized"

Access tokens

Personal, project, or group access tokens are used similarly, i.e., via a private-token request header.

You can generate a PAT from your profile.


Tokens are secret. Handle them securely like you would a sign-in password.

Project and group tokens are generated from the Settings -> Access Tokens menu.

Example of using personal, project, or group access token in a request header:

curl --header "private-token: your_access_token" ""

Example response:

"id": 21816,
"description": "Example project description",
"name": "Example project name",

When working on the command line, consider using a JSON formatter like jq to beautify the JSON responses.

Pipeline trigger tokens

A pipeline trigger token is scoped only for triggering a pipeline.

For detailed steps on getting a pipeline trigger token, refer to our Running pipelines - Pipeline trigger.


Offset-based pagination

Sometimes, the response spans many pages. When listing resources, you can pass the following query parameters:

pagePage number (default: 1)
per_pageNumber of items to list per page (default: 20, max: 100)

Example of using the page and per_page query parameters:

curl --header "private-token: your_access_token" ""

Example response:

"id": 320941,
"name": "Example group name",
"path": "example-group-name",
"kind": "group",

Learn more about query parameters in a URL query string via Wikipedia.

Request payload

JSON supports a JSON request payload when making PUT and POST requests.

Example of sending a request with a data payload:

curl --request POST --header "Content-Type: application/json" \
--data '{"name":"<example-name>", "description":"<example-description>"}' ""

Form fields supports using the form submission type when making PUT and POST requests.

Example of sending a request with a form type:

curl --request POST \
--form "name=<example-name>" \
--form "description=<example-description>" \
--form "permissions[project_access]=null"

Content type

The API supports the application/JSON content type by default.