path: root/doc/api/openapi/openapi.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