699 lines
20 KiB
YAML
699 lines
20 KiB
YAML
openapi: 3.0.0
|
|
tags:
|
|
- name: metadata
|
|
description: Metadata of the GitLab instance
|
|
- name: version
|
|
description: Version
|
|
- name: access_requests
|
|
description: Access requests for projects and groups
|
|
- name: access_tokens
|
|
description: Access tokens for projects
|
|
info:
|
|
description: |
|
|
An OpenAPI definition for the GitLab REST API.
|
|
Few API resources or endpoints are currently included.
|
|
The intent is to expand this to match the entire Markdown documentation of the API:
|
|
<https://docs.gitlab.com/ee/api/>. Contributions are welcome.
|
|
|
|
When viewing this on gitlab.com, you can test API calls directly from the browser
|
|
against the `gitlab.com` instance, if you are logged in.
|
|
The feature uses the current [GitLab session cookie](https://docs.gitlab.com/ee/api/index.html#session-cookie),
|
|
so each request is made using your account.
|
|
|
|
Instructions for using this tool can be found in [Interactive API Documentation](openapi_interactive.md).
|
|
|
|
version: v4
|
|
title: GitLab API
|
|
termsOfService: 'https://about.gitlab.com/terms/'
|
|
license:
|
|
name: CC BY-SA 4.0
|
|
url: 'https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE'
|
|
servers:
|
|
- url: 'https://gitlab.com/api/'
|
|
security:
|
|
- ApiKeyAuth: []
|
|
|
|
components:
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
type: apiKey
|
|
in: header
|
|
name: Private-Token
|
|
|
|
paths:
|
|
# METADATA
|
|
/v4/metadata:
|
|
$ref: '#/metadata'
|
|
|
|
# VERSION
|
|
/v4/version:
|
|
$ref: '#/version'
|
|
|
|
# ACCESS REQUESTS (PROJECTS)
|
|
/v4/projects/{id}/access_requests:
|
|
$ref: '#/accessRequestsProjects'
|
|
|
|
/v4/projects/{id}/access_requests/{user_id}/approve:
|
|
$ref: '#/accessRequestsProjectsApprove'
|
|
|
|
/v4/projects/{id}/access_requests/{user_id}:
|
|
$ref: '#/accessRequestsProjectsDeny'
|
|
|
|
# ACCESS REQUESTS (GROUPS)
|
|
/v4/groups/{id}/access_requests:
|
|
$ref: '#/accessRequestsGroups'
|
|
|
|
/v4/groups/{id}/access_requests/{user_id}/approve:
|
|
$ref: '#/accessRequestsGroupsApprove'
|
|
|
|
/v4/groups/{id}/access_requests/{user_id}:
|
|
$ref: '#/accessRequestsGroupsDeny'
|
|
|
|
# ACCESS REQUESTS (PROJECTS)
|
|
/v4/projects/{id}/access_tokens:
|
|
$ref: '#/accessTokens'
|
|
|
|
/v4/projects/{id}/access_tokens/{token_id}:
|
|
$ref: '#/accessTokensRevoke'
|
|
|
|
metadata:
|
|
get:
|
|
tags:
|
|
- metadata
|
|
summary: 'Retrieve metadata information for this GitLab instance.'
|
|
operationId: 'getMetadata'
|
|
responses:
|
|
'401':
|
|
description: 'unauthorized operation'
|
|
'200':
|
|
description: 'successful operation'
|
|
content:
|
|
'application/json':
|
|
schema:
|
|
title: 'MetadataResponse'
|
|
type: 'object'
|
|
properties:
|
|
version:
|
|
type: 'string'
|
|
revision:
|
|
type: 'string'
|
|
kas:
|
|
type: 'object'
|
|
properties:
|
|
enabled:
|
|
type: 'boolean'
|
|
externalUrl:
|
|
type: 'string'
|
|
nullable: true
|
|
version:
|
|
type: 'string'
|
|
nullable: true
|
|
examples:
|
|
Example:
|
|
value:
|
|
version: '15.0-pre'
|
|
revision: 'c401a659d0c'
|
|
kas:
|
|
enabled: true
|
|
externalUrl: 'grpc://gitlab.example.com:8150'
|
|
version: '15.0.0'
|
|
|
|
version:
|
|
get:
|
|
tags:
|
|
- version
|
|
summary: 'Retrieve version information for this GitLab instance.'
|
|
operationId: 'getVersion'
|
|
responses:
|
|
'401':
|
|
description: 'unauthorized operation'
|
|
'200':
|
|
description: 'successful operation'
|
|
content:
|
|
'application/json':
|
|
schema:
|
|
title: 'VersionResponse'
|
|
type: 'object'
|
|
properties:
|
|
version:
|
|
type: 'string'
|
|
revision:
|
|
type: 'string'
|
|
examples:
|
|
Example:
|
|
value:
|
|
version: '13.3.0-pre'
|
|
revision: 'f2b05afebb0'
|
|
|
|
#/v4/projects/{id}/access_requests
|
|
accessRequestsProjects:
|
|
get:
|
|
description: Lists access requests for a project
|
|
summary: List access requests for a project
|
|
operationId: accessRequestsProjects_get
|
|
tags:
|
|
- access_requests
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the project owned by the authenticated user.
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
responses:
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
title: ProjectAccessResponse
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
usename:
|
|
type: string
|
|
name:
|
|
type: string
|
|
state:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
requested_at:
|
|
type: string
|
|
example:
|
|
- 'id': 1
|
|
'username': 'raymond_smith'
|
|
'name': 'Raymond Smith'
|
|
'state': 'active'
|
|
'created_at': '2012-10-22T14:13:35Z'
|
|
'requested_at': '2012-10-22T14:13:35Z'
|
|
- 'id': 2
|
|
'username': 'john_doe'
|
|
'name': 'John Doe'
|
|
'state': 'active'
|
|
'created_at': '2012-10-22T14:13:35Z'
|
|
'requested_at': '2012-10-22T14:13:35Z'
|
|
post:
|
|
description: Requests access for the authenticated user to a project
|
|
summary: Requests access for the authenticated user to a project
|
|
operationId: accessRequestsProjects_post
|
|
tags:
|
|
- access_requests
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the project owned by the authenticated user.
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
responses:
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
title: ProjectAccessRequest
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
usename:
|
|
type: string
|
|
name:
|
|
type: string
|
|
state:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
requested_at:
|
|
type: string
|
|
example:
|
|
'id': 1
|
|
'username': 'raymond_smith'
|
|
'name': 'Raymond Smith'
|
|
'state': 'active'
|
|
'created_at': '2012-10-22T14:13:35Z'
|
|
'requested_at': '2012-10-22T14:13:35Z'
|
|
|
|
#/v4/projects/{id}/access_requests/{user_id}/approve
|
|
accessRequestsProjectsApprove:
|
|
put:
|
|
description: Approves access for the authenticated user to a project
|
|
summary: Approves access for the authenticated user to a project
|
|
operationId: accessRequestsProjectsApprove_put
|
|
tags:
|
|
- access_requests
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the project owned by the authenticated user.
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
- name: user_id
|
|
in: path
|
|
description: The userID of the access requester
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- name: access_level
|
|
in: query
|
|
description: A valid project access level. 0 = no access , 10 = guest, 20 = reporter, 30 = developer, 40 = Maintainer. Default is 30.'
|
|
required: false
|
|
schema:
|
|
enum: [0, 10, 20, 30, 40]
|
|
default: 30
|
|
type: integer
|
|
responses:
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
title: ProjectAccessApprove
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
usename:
|
|
type: string
|
|
name:
|
|
type: string
|
|
state:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
access_level:
|
|
type: integer
|
|
example:
|
|
'id': 1
|
|
'username': 'raymond_smith'
|
|
'name': 'Raymond Smith'
|
|
'state': 'active'
|
|
'created_at': '2012-10-22T14:13:35Z'
|
|
'access_level': 20
|
|
|
|
#/v4/projects/{id}/access_requests/{user_id}
|
|
accessRequestsProjectsDeny:
|
|
delete:
|
|
description: Denies a project access request for the given user
|
|
summary: Denies a project access request for the given user
|
|
operationId: accessRequestProjectsDeny_delete
|
|
tags:
|
|
- access_requests
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the project owned by the authenticated user.
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
- name: user_id
|
|
in: path
|
|
description: The user ID of the access requester
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses: # Does anything go here? Markdown doc does not list a response.
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
|
|
#/v4/groups/{id}/access_requests
|
|
accessRequestsGroups:
|
|
get:
|
|
description: List access requests for a group
|
|
summary: List access requests for a group
|
|
operationId: accessRequestsGroups_get
|
|
tags:
|
|
- access_requests
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the group owned by the authenticated user.
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
responses:
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
title: GroupAccessResponse
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
usename:
|
|
type: string
|
|
name:
|
|
type: string
|
|
state:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
requested_at:
|
|
type: string
|
|
example:
|
|
- 'id': 1
|
|
'username': 'raymond_smith'
|
|
'name': 'Raymond Smith'
|
|
'state': 'active'
|
|
'created_at': '2012-10-22T14:13:35Z'
|
|
'requested_at': '2012-10-22T14:13:35Z'
|
|
- 'id': 2
|
|
'username': 'john_doe'
|
|
'name': 'John Doe'
|
|
'state': 'active'
|
|
'created_at': '2012-10-22T14:13:35Z'
|
|
'requested_at': '2012-10-22T14:13:35Z'
|
|
post:
|
|
description: Requests access for the authenticated user to a group
|
|
summary: Requests access for the authenticated user to a group
|
|
operationId: accessRequestsGroups_post
|
|
tags:
|
|
- access_requests
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the group owned by the authenticated user.
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
responses:
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
title: GroupAccessRequest
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
usename:
|
|
type: string
|
|
name:
|
|
type: string
|
|
state:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
requested_at:
|
|
type: string
|
|
example:
|
|
'id': 1
|
|
'username': 'raymond_smith'
|
|
'name': 'Raymond Smith'
|
|
'state': 'active'
|
|
'created_at': '2012-10-22T14:13:35Z'
|
|
'requested_at': '2012-10-22T14:13:35Z'
|
|
|
|
#/v4/groups/{id}/access_requests/{user_id}/approve
|
|
accessRequestsGroupsApprove:
|
|
put:
|
|
description: Approves access for the authenticated user to a group
|
|
summary: Approves access for the authenticated user to a group
|
|
operationId: accessRequestsGroupsApprove_put
|
|
tags:
|
|
- access_requests
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the group owned by the authenticated user.
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
- name: user_id
|
|
in: path
|
|
description: The userID of the access requester
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- name: access_level
|
|
in: query
|
|
description: A valid group access level. 0 = no access , 10 = Guest, 20 = Reporter, 30 = Developer, 40 = Maintainer, 50 = Owner. Default is 30.
|
|
required: false
|
|
schema:
|
|
enum: [0, 10, 20, 30, 40, 50]
|
|
default: 30
|
|
type: integer
|
|
responses:
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
title: GroupAccessApprove
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
usename:
|
|
type: string
|
|
name:
|
|
type: string
|
|
state:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
access_level:
|
|
type: integer
|
|
example:
|
|
'id': 1
|
|
'username': 'raymond_smith'
|
|
'name': 'Raymond Smith'
|
|
'state': 'active'
|
|
'created_at': '2012-10-22T14:13:35Z'
|
|
'access_level': 20
|
|
|
|
#/v4/groups/{id}/access_requests/{user_id}
|
|
accessRequestsGroupsDeny:
|
|
delete:
|
|
description: Denies a group access request for the given user
|
|
summary: Denies a group access request for the given user
|
|
operationId: accessRequestsGroupsDeny_delete
|
|
tags:
|
|
- access_requests
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the group owned by the authenticated user.
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
- name: user_id
|
|
in: path
|
|
description: The userID of the access requester
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses: # Does anything go here? Markdown doc does not list a response.
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
#/v4/projects/{id}/access_tokens
|
|
accessTokens:
|
|
get:
|
|
description: Lists access tokens for a project
|
|
summary: List access tokens for a project
|
|
operationId: accessTokens_get
|
|
tags:
|
|
- access_tokens
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the project
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
responses:
|
|
'404':
|
|
description: Not Found
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
title: AccessTokenList
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
scopes:
|
|
type: array
|
|
name:
|
|
type: string
|
|
expires_at:
|
|
type: date
|
|
id:
|
|
type: integer
|
|
active:
|
|
type: boolean
|
|
created_at:
|
|
type: date
|
|
revoked:
|
|
type: boolean
|
|
example:
|
|
'user_id': 141
|
|
'scopes': ['api']
|
|
'name': 'token'
|
|
'expires_at': '2022-01-31'
|
|
'id': 42
|
|
'active': true
|
|
'created_at': '2021-01-20T14:13:35Z'
|
|
'revoked': false
|
|
post:
|
|
description: Creates an access token for a project
|
|
summary: Creates an access token for a project
|
|
operationId: accessTokens_post
|
|
tags:
|
|
- access_tokens
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the project
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
- name: name
|
|
in: query
|
|
description: The name of the project access token
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- name: scopes
|
|
in: query
|
|
description: Defines read and write permissions for the token
|
|
required: true
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum:
|
|
[
|
|
'api',
|
|
'read_api',
|
|
'read_registry',
|
|
'write_registry',
|
|
'read_repository',
|
|
'write_repository',
|
|
]
|
|
- name: expires_at
|
|
in: query
|
|
description: Date when the token expires. Time of day is Midnight UTC of that date.
|
|
required: false
|
|
schema:
|
|
type: date
|
|
responses:
|
|
'404':
|
|
description: Not Found
|
|
'401':
|
|
description: Unauthorized operation
|
|
'200':
|
|
description: Successful operation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
title: AccessTokenList
|
|
type: object
|
|
properties:
|
|
user_id:
|
|
type: integer
|
|
scopes:
|
|
type: array
|
|
name:
|
|
type: string
|
|
expires_at:
|
|
type: date
|
|
id:
|
|
type: integer
|
|
active:
|
|
type: boolean
|
|
created_at:
|
|
type: date
|
|
revoked:
|
|
type: boolean
|
|
token:
|
|
type: string
|
|
example:
|
|
'user_id': 166
|
|
'scopes': ['api', 'read_repository']
|
|
'name': 'test'
|
|
'expires_at': '2022-01-31'
|
|
'id': 58
|
|
'active': true
|
|
'created_at': '2021-01-20T14:13:35Z'
|
|
'revoked': false
|
|
'token': 'D4y...Wzr'
|
|
|
|
#/v4/projects/{id}/access_tokens/{token_id}
|
|
accessTokensRevoke:
|
|
delete:
|
|
description: Revokes an access token
|
|
summary: Revokes an access token
|
|
operationId: accessTokens_delete
|
|
tags:
|
|
- access_tokens
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The ID or URL-encoded path of the project
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
- name: token_id
|
|
in: path
|
|
description: The ID of the project access token
|
|
required: true
|
|
schema:
|
|
oneOf:
|
|
- type: integer
|
|
- type: string
|
|
responses:
|
|
'400':
|
|
description: Bad Request
|
|
'404':
|
|
description: Not Found
|
|
'204':
|
|
description: No content if successfully revoked
|