OpenAPI

GitLab documents its REST API using the OpenAPI 3.0 specification (formerly called Swagger), a standard, platform-independent format for describing RESTful APIs. The API code is the single source of truth for the REST API. The OpenAPI spec is autogenerated directly from the API code and is tightly coupled to its implementation, ensuring the documentation is always accurate and up to date.

For general information about the GitLab APIs, see Extend with GitLab.

OpenAPI specification file

The raw OpenAPI 3.0 specification is available in the GitLab monorepo:

• File: doc/api/openapi/openapi_v3.yaml
• Format: OpenAPI 3.0 (YAML)

[!note] The OpenAPI 2.0 specification (openapi_v2.yaml) is deprecated and no longer receives updates. Use the OpenAPI 3.0 specification (openapi_v3.yaml) instead.

Interactive REST API documentation

The REST API is documented in full using the OpenAPI 3.0 specification. You can browse and test every endpoint interactively in the REST API documentation.

The documentation is rendered using Scalar, an open-source API reference tool. It is generated automatically from the OpenAPI spec in the GitLab source code, so it always reflects the current state of the API.

Add authorization credentials

Some endpoints require authentication. GitLab supports authentication with HTTP Bearer or OAuth 2.0 credentials.

To add authorization credentials:

1. Go to the REST API documentation.
2. In the Authentication panel on the right, select an authentication method from the dropdown list.
3. Enter your credentials:
   • For http, enter your personal access token.
   • For oauth2, use the authorization code flow with GitLab as the identity provider.
4. Select Authorize.

Your credentials are reused automatically for all subsequent requests during the session.

Send a live request

Use the interactive request tool to send live requests to GitLab.

To send a live request:

1. Go to the REST API documentation.
2. Expand an operation.
3. Select Test Request.
4. Enter any required or optional parameters.
5. Select Send.

The tool displays the curl command, the full request URL, and the server response.