@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api GitLab API
@base https://www.gitlab.com/api/v4
@version v4
@auth ApiKey Private-Token in header
@endpoints 73
@hint download_for_search
@toc groups(10), projects(26), admin(16), applications(3), avatar(1), broadcast_messages(5), bulk_imports(6), application(4), metadata(1), version(1)

@group groups
@endpoint GET /groups/{id}/badges/{badge_id}
@desc Gets a badge of a group.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user., badge_id: int(int32) # The badge ID}
@returns(200) {name: str, link_url: str, image_url: str, rendered_link_url: str, rendered_image_url: str, id: str, kind: str} # Gets a badge of a group.

@endpoint PUT /groups/{id}/badges/{badge_id}
@desc Updates a badge of a group.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user., badge_id: int(int32)}
@optional {link_url: str # URL of the badge link, image_url: str # URL of the badge image, name: str # Name for the badge}
@returns(200) {name: str, link_url: str, image_url: str, rendered_link_url: str, rendered_image_url: str, id: str, kind: str} # Updates a badge of a group.

@endpoint DELETE /groups/{id}/badges/{badge_id}
@desc Removes a badge from the group.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user., badge_id: int(int32) # The badge ID}
@returns(204) Removes a badge from the group.

@endpoint GET /groups/{id}/badges
@desc Gets a list of group badges viewable by the authenticated user.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user.}
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page, name: str # Name for the badge}
@returns(200) Gets a list of group badges viewable by the authenticated user.

@endpoint POST /groups/{id}/badges
@desc Adds a badge to a group.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user., link_url: str # URL of the badge link, image_url: str # URL of the badge image}
@optional {name: str # Name for the badge}
@returns(201) {name: str, link_url: str, image_url: str, rendered_link_url: str, rendered_image_url: str, id: str, kind: str} # Adds a badge to a group.

@endpoint GET /groups/{id}/badges/render
@desc Preview a badge from a group.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user., link_url: str # URL of the badge link, image_url: str # URL of the badge image}
@returns(200) {name: str, link_url: str, image_url: str, rendered_link_url: str, rendered_image_url: str} # Preview a badge from a group.

@endpoint DELETE /groups/{id}/access_requests/{user_id}
@desc Denies an access request for the given user.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user, user_id: int(int32) # The user ID of the access requester}
@returns(204) Denies an access request for the given user.

@endpoint PUT /groups/{id}/access_requests/{user_id}/approve
@desc Approves an access request for the given user.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user, user_id: int(int32) # The user ID of the access requester}
@optional {access_level: int(int32)=30 # A valid access level (defaults: `30`, the Developer role)}
@returns(200) {id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str, requested_at: str} # successful operation

@endpoint GET /groups/{id}/access_requests
@desc Gets a list of access requests for a group.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user}
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page}
@returns(200) {id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str, requested_at: str} # Gets a list of access requests for a group.

@endpoint POST /groups/{id}/access_requests
@desc Requests access for the authenticated user to a group.
@required {id: str # The ID or URL-encoded path of the group owned by the authenticated user}
@returns(200) {id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str, requested_at: str} # successful operation

@endgroup

@group projects
@endpoint DELETE /projects/{id}/repository/merged_branches
@desc Delete all merged branches
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).}
@returns(202) 202 Accepted
@errors {404: 404 Project Not Found}

@endpoint GET /projects/{id}/repository/branches/{branch}
@desc Get a single repository branch
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., branch: int(int32)}
@returns(200) {name: str, commit: map{id: str, short_id: str, created_at: str(date-time), parent_ids: [str], title: str, message: str, author_name: str, author_email: str, authored_date: str(date-time), committer_name: str, committer_email: str, committed_date: str(date-time), trailers: map, web_url: str}, merged: bool, protected: bool, developers_can_push: bool, developers_can_merge: bool, can_push: bool, default: bool, web_url: str} # Get a single repository branch
@errors {404: Branch Not Found}

@endpoint DELETE /projects/{id}/repository/branches/{branch}
@desc Delete a branch
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., branch: str # The name of the branch}
@returns(204) Delete a branch
@errors {404: Branch Not Found}

@endpoint HEAD /projects/{id}/repository/branches/{branch}
@desc Check if a branch exists
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., branch: str # The name of the branch}
@returns(204) No Content
@errors {404: Not Found}

@endpoint GET /projects/{id}/repository/branches
@desc Get a project repository branches
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).}
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page, search: str # Return list of branches matching the search criteria, regex: str # Return list of branches matching the regex, sort: str(name_asc/updated_asc/updated_desc) # Return list of branches sorted by the given field, page_token: str # Name of branch to start the pagination from}
@returns(200) Get a project repository branches
@errors {404: 404 Project Not Found}

@endpoint POST /projects/{id}/repository/branches
@desc Create branch
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., branch: str # The name of the branch, ref: str # Create branch from commit sha or existing branch}
@returns(201) {name: str, commit: map{id: str, short_id: str, created_at: str(date-time), parent_ids: [str], title: str, message: str, author_name: str, author_email: str, authored_date: str(date-time), committer_name: str, committer_email: str, committed_date: str(date-time), trailers: map, web_url: str}, merged: bool, protected: bool, developers_can_push: bool, developers_can_merge: bool, can_push: bool, default: bool, web_url: str} # Create branch
@errors {400: Failed to create branch}

@endpoint PUT /projects/{id}/repository/branches/{branch}/unprotect
@desc Unprotect a single branch
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., branch: str # The name of the branch}
@returns(200) {name: str, commit: map{id: str, short_id: str, created_at: str(date-time), parent_ids: [str], title: str, message: str, author_name: str, author_email: str, authored_date: str(date-time), committer_name: str, committer_email: str, committed_date: str(date-time), trailers: map, web_url: str}, merged: bool, protected: bool, developers_can_push: bool, developers_can_merge: bool, can_push: bool, default: bool, web_url: str} # Unprotect a single branch
@errors {404: 404 Project Not Found}

@endpoint PUT /projects/{id}/repository/branches/{branch}/protect
@desc Protect a single branch
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., branch: str # The name of the branch}
@optional {developers_can_push: bool # Flag if developers can push to that branch, developers_can_merge: bool # Flag if developers can merge to that branch}
@returns(200) {name: str, commit: map{id: str, short_id: str, created_at: str(date-time), parent_ids: [str], title: str, message: str, author_name: str, author_email: str, authored_date: str(date-time), committer_name: str, committer_email: str, committed_date: str(date-time), trailers: map, web_url: str}, merged: bool, protected: bool, developers_can_push: bool, developers_can_merge: bool, can_push: bool, default: bool, web_url: str} # Protect a single branch
@errors {404: 404 Branch Not Found}

@endpoint GET /projects/{id}/badges/{badge_id}
@desc Gets a badge of a project.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., badge_id: int(int32) # The badge ID}
@returns(200) {name: str, link_url: str, image_url: str, rendered_link_url: str, rendered_image_url: str, id: str, kind: str} # Gets a badge of a project.

@endpoint PUT /projects/{id}/badges/{badge_id}
@desc Updates a badge of a project.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., badge_id: int(int32)}
@optional {link_url: str # URL of the badge link, image_url: str # URL of the badge image, name: str # Name for the badge}
@returns(200) {name: str, link_url: str, image_url: str, rendered_link_url: str, rendered_image_url: str, id: str, kind: str} # Updates a badge of a project.

@endpoint DELETE /projects/{id}/badges/{badge_id}
@desc Removes a badge from the project.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., badge_id: int(int32) # The badge ID}
@returns(204) Removes a badge from the project.

@endpoint GET /projects/{id}/badges
@desc Gets a list of project badges viewable by the authenticated user.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).}
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page, name: str # Name for the badge}
@returns(200) Gets a list of project badges viewable by the authenticated user.

@endpoint POST /projects/{id}/badges
@desc Adds a badge to a project.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., link_url: str # URL of the badge link, image_url: str # URL of the badge image}
@optional {name: str # Name for the badge}
@returns(201) {name: str, link_url: str, image_url: str, rendered_link_url: str, rendered_image_url: str, id: str, kind: str} # Adds a badge to a project.

@endpoint GET /projects/{id}/badges/render
@desc Preview a badge from a project.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., link_url: str # URL of the badge link, image_url: str # URL of the badge image}
@returns(200) {name: str, link_url: str, image_url: str, rendered_link_url: str, rendered_image_url: str} # Preview a badge from a project.

@endpoint DELETE /projects/{id}/access_requests/{user_id}
@desc Denies an access request for the given user.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., user_id: int(int32) # The user ID of the access requester}
@returns(204) Denies an access request for the given user.

@endpoint PUT /projects/{id}/access_requests/{user_id}/approve
@desc Approves an access request for the given user.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., user_id: int(int32) # The user ID of the access requester}
@optional {access_level: int(int32)=30 # A valid access level (defaults: `30`, the Developer role)}
@returns(200) {id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str, requested_at: str} # successful operation

@endpoint GET /projects/{id}/access_requests
@desc Gets a list of access requests for a project.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).}
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page}
@returns(200) {id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str, requested_at: str} # Gets a list of access requests for a project.

@endpoint POST /projects/{id}/access_requests
@desc Requests access for the authenticated user to a project.
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).}
@returns(200) {id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str, requested_at: str} # successful operation

@endpoint PUT /projects/{id}/alert_management_alerts/{alert_iid}/metric_images/{metric_image_id}
@desc Update a metric image for an alert
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., alert_iid: int(int32) # The IID of the Alert, metric_image_id: int(int32) # The ID of metric image}
@returns(200) {id: int(int32), created_at: str(date-time), filename: str, file_path: str, url: str, url_text: str} # Update a metric image for an alert
@errors {403: Forbidden, 422: Unprocessable entity}

@endpoint DELETE /projects/{id}/alert_management_alerts/{alert_iid}/metric_images/{metric_image_id}
@desc Remove a metric image for an alert
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., alert_iid: int(int32) # The IID of the Alert, metric_image_id: int(int32) # The ID of metric image}
@returns(204) {id: int(int32), created_at: str(date-time), filename: str, file_path: str, url: str, url_text: str} # Remove a metric image for an alert
@errors {403: Forbidden, 422: Unprocessable entity}

@endpoint GET /projects/{id}/alert_management_alerts/{alert_iid}/metric_images
@desc Metric Images for alert
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., alert_iid: int(int32) # The IID of the Alert}
@returns(200) Metric Images for alert
@errors {404: Not found}

@endpoint POST /projects/{id}/alert_management_alerts/{alert_iid}/metric_images
@desc Upload a metric image for an alert
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., alert_iid: int(int32) # The IID of the Alert}
@returns(200) {id: int(int32), created_at: str(date-time), filename: str, file_path: str, url: str, url_text: str} # Upload a metric image for an alert
@errors {403: Forbidden}

@endpoint POST /projects/{id}/alert_management_alerts/{alert_iid}/metric_images/authorize
@desc Workhorse authorize metric image file upload
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., alert_iid: int(int32) # The IID of the Alert}
@returns(200) Workhorse authorize metric image file upload
@errors {403: Forbidden}

@endgroup

@group admin
@endpoint GET /admin/batched_background_migrations/{id}
@desc Retrieve a batched background migration
@required {id: int(int32) # The batched background migration id}
@optional {database: str(main/ci/embedding/geo)=main # The name of the database}
@returns(200) {id: str, job_class_name: str, table_name: str, status: str, progress: num(float), created_at: str(date-time)} # Retrieve a batched background migration
@errors {401: 401 Unauthorized, 403: 403 Forbidden, 404: 404 Not found}

@endpoint GET /admin/batched_background_migrations
@desc Get the list of batched background migrations
@optional {database: str(main/ci/embedding/geo)=main # The name of the database, the default `main`}
@returns(200) Get the list of batched background migrations
@errors {401: 401 Unauthorized, 403: 403 Forbidden}

@endpoint PUT /admin/batched_background_migrations/{id}/resume
@desc Resume a batched background migration
@required {id: int(int32) # The batched background migration id}
@optional {database: str(main/ci/embedding/geo)=main # The name of the database}
@returns(200) {id: str, job_class_name: str, table_name: str, status: str, progress: num(float), created_at: str(date-time)} # Resume a batched background migration
@errors {401: 401 Unauthorized, 403: 403 Forbidden, 404: 404 Not found, 422: You can resume only `paused` batched background migrations.}

@endpoint PUT /admin/batched_background_migrations/{id}/pause
@desc Pause a batched background migration
@required {id: int(int32) # The batched background migration id}
@optional {database: str(main/ci/embedding/geo)=main # The name of the database}
@returns(200) {id: str, job_class_name: str, table_name: str, status: str, progress: num(float), created_at: str(date-time)} # Pause a batched background migration
@errors {401: 401 Unauthorized, 403: 403 Forbidden, 404: 404 Not found, 422: You can pause only `active` batched background migrations.}

@endpoint GET /admin/ci/variables/{key}
@desc Get the details of a specific instance-level variable
@required {key: str # The key of a variable}
@returns(200) {variable_type: str, key: str, value: str, protected: bool, masked: bool, raw: bool, environment_scope: str} # Get the details of a specific instance-level variable
@errors {404: Instance Variable Not Found}

@endpoint PUT /admin/ci/variables/{key}
@desc Update an instance-level variable
@required {key: str # The key of a variable}
@optional {value: str # The value of a variable, protected: bool # Whether the variable is protected, masked: bool # Whether the variable is masked, raw: bool # Whether the variable will be expanded, variable_type: str(env_var/file) # The type of a variable. Available types are: env_var (default) and file}
@returns(200) {variable_type: str, key: str, value: str, protected: bool, masked: bool, raw: bool, environment_scope: str} # Update an instance-level variable
@errors {404: Instance Variable Not Found}

@endpoint DELETE /admin/ci/variables/{key}
@desc Delete an existing instance-level variable
@required {key: str # The key of a variable}
@returns(204) {variable_type: str, key: str, value: str, protected: bool, masked: bool, raw: bool, environment_scope: str} # Delete an existing instance-level variable
@errors {404: Instance Variable Not Found}

@endpoint GET /admin/ci/variables
@desc List all instance-level variables
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page}
@returns(200) {variable_type: str, key: str, value: str, protected: bool, masked: bool, raw: bool, environment_scope: str} # List all instance-level variables

@endpoint POST /admin/ci/variables
@desc Create a new instance-level variable
@required {key: str # The key of the variable. Max 255 characters, value: str # The value of a variable}
@optional {protected: bool # Whether the variable is protected, masked: bool # Whether the variable is masked, raw: bool # Whether the variable will be expanded, variable_type: str(env_var/file) # The type of a variable. Available types are: env_var (default) and file}
@returns(201) {variable_type: str, key: str, value: str, protected: bool, masked: bool, raw: bool, environment_scope: str} # Create a new instance-level variable
@errors {400: 400 Bad Request}

@endpoint GET /admin/databases/{database_name}/dictionary/tables/{table_name}
@desc Retrieve dictionary details
@required {database_name: str(main/ci) # The database name, table_name: str # The table name}
@returns(200) {table_name: str, feature_categories: [str]} # Retrieve dictionary details
@errors {401: 401 Unauthorized, 403: 403 Forbidden, 404: 404 Not found}

@endpoint GET /admin/clusters/{cluster_id}
@desc Get a single instance cluster
@required {cluster_id: int(int32) # The cluster ID}
@returns(200) {id: str, name: str, created_at: str, domain: str, enabled: str, managed: str, provider_type: str, platform_type: str, environment_scope: str, cluster_type: str, namespace_per_environment: str, user: map{id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str}, platform_kubernetes: map{api_url: str, namespace: str, authorization_type: str, ca_cert: str}, provider_gcp: map{cluster_id: str, status_name: str, gcp_project_id: str, zone: str, machine_type: str, num_nodes: str, endpoint: str}, management_project: map{id: int(int32), description: str, name: str, name_with_namespace: str, path: str, path_with_namespace: str, created_at: str(date-time)}} # Get a single instance cluster
@errors {403: Forbidden, 404: Not found}

@endpoint PUT /admin/clusters/{cluster_id}
@desc Edit instance cluster
@required {cluster_id: int(int32) # The cluster ID}
@optional {name: str # Cluster name, enabled: bool # Enable or disable Gitlab's connection to your Kubernetes cluster, environment_scope: str # The associated environment to the cluster, namespace_per_environment: bool=true # Deploy each environment to a separate Kubernetes namespace, domain: str # Cluster base domain, management_project_id: int(int32) # The ID of the management project, managed: bool # Determines if GitLab will manage namespaces and service accounts for this cluster, platform_kubernetes_attributes[api_url]: str # URL to access the Kubernetes API, platform_kubernetes_attributes[token]: str # Token to authenticate against Kubernetes, platform_kubernetes_attributes[ca_cert]: str # TLS certificate (needed if API is using a self-signed TLS certificate), platform_kubernetes_attributes[namespace]: str # Unique namespace related to Project}
@returns(200) {id: str, name: str, created_at: str, domain: str, enabled: str, managed: str, provider_type: str, platform_type: str, environment_scope: str, cluster_type: str, namespace_per_environment: str, user: map{id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str}, platform_kubernetes: map{api_url: str, namespace: str, authorization_type: str, ca_cert: str}, provider_gcp: map{cluster_id: str, status_name: str, gcp_project_id: str, zone: str, machine_type: str, num_nodes: str, endpoint: str}, management_project: map{id: int(int32), description: str, name: str, name_with_namespace: str, path: str, path_with_namespace: str, created_at: str(date-time)}} # Edit instance cluster
@errors {400: Validation error, 403: Forbidden, 404: Not found}

@endpoint DELETE /admin/clusters/{cluster_id}
@desc Delete instance cluster
@required {cluster_id: int(int32) # The cluster ID}
@returns(204) {id: str, name: str, created_at: str, domain: str, enabled: str, managed: str, provider_type: str, platform_type: str, environment_scope: str, cluster_type: str, namespace_per_environment: str, user: map{id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str}, platform_kubernetes: map{api_url: str, namespace: str, authorization_type: str, ca_cert: str}, provider_gcp: map{cluster_id: str, status_name: str, gcp_project_id: str, zone: str, machine_type: str, num_nodes: str, endpoint: str}, management_project: map{id: int(int32), description: str, name: str, name_with_namespace: str, path: str, path_with_namespace: str, created_at: str(date-time)}} # Delete instance cluster
@errors {403: Forbidden, 404: Not found}

@endpoint POST /admin/clusters/add
@desc Add existing instance cluster
@required {name: str # Cluster name, platform_kubernetes_attributes[api_url]: str # URL to access the Kubernetes API, platform_kubernetes_attributes[token]: str # Token to authenticate against Kubernetes}
@optional {enabled: bool=true # Determines if cluster is active or not, defaults to true, environment_scope: str=* # The associated environment to the cluster, namespace_per_environment: bool=true # Deploy each environment to a separate Kubernetes namespace, domain: str # Cluster base domain, management_project_id: int(int32) # The ID of the management project, managed: bool=true # Determines if GitLab will manage namespaces and service accounts for this cluster, defaults to true, platform_kubernetes_attributes[ca_cert]: str # TLS certificate (needed if API is using a self-signed TLS certificate), platform_kubernetes_attributes[namespace]: str # Unique namespace related to Project, platform_kubernetes_attributes[authorization_type]: str(unknown_authorization/rbac/abac)=rbac # Cluster authorization type, defaults to RBAC}
@returns(201) {id: str, name: str, created_at: str, domain: str, enabled: str, managed: str, provider_type: str, platform_type: str, environment_scope: str, cluster_type: str, namespace_per_environment: str, user: map{id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str}, platform_kubernetes: map{api_url: str, namespace: str, authorization_type: str, ca_cert: str}, provider_gcp: map{cluster_id: str, status_name: str, gcp_project_id: str, zone: str, machine_type: str, num_nodes: str, endpoint: str}, management_project: map{id: int(int32), description: str, name: str, name_with_namespace: str, path: str, path_with_namespace: str, created_at: str(date-time)}} # Add existing instance cluster
@errors {400: Validation error, 403: Forbidden, 404: Not found}

@endpoint GET /admin/clusters
@desc List instance clusters
@returns(200) List instance clusters
@errors {403: Forbidden}

@endpoint POST /admin/migrations/{timestamp}/mark
@desc Mark the migration as successfully executed
@required {timestamp: int(int32) # The migration version timestamp}
@optional {database: str(main/ci/embedding/geo)=main # The name of the database}
@returns(201) 201 Created
@errors {401: 401 Unauthorized, 403: 403 Forbidden, 404: 404 Not found, 422: You can mark only pending migrations}

@endgroup

@group applications
@endpoint DELETE /applications/{id}
@desc Delete an application
@required {id: int(int32) # The ID of the application (not the application_id)}
@returns(204) Delete an application

@endpoint GET /applications
@desc Get applications
@returns(200) Get applications

@endpoint POST /applications
@desc Create a new application
@required {name: str # Name of the application., redirect_uri: str # Redirect URI of the application., scopes: str # Scopes of the application. You can specify multiple scopes by separating\                                  each scope using a space}
@optional {confidential: bool=true # The application is used where the client secret can be kept confidential. Native mobile apps \                         and Single Page Apps are considered non-confidential. Defaults to true if not supplied}
@returns(200) {id: str, application_id: str, application_name: str, callback_url: str, confidential: bool, secret: str} # Create a new application

@endgroup

@group avatar
@endpoint GET /avatar
@desc Return avatar url for a user
@required {email: str # Public email address of the user}
@optional {size: int(int32) # Single pixel dimension for Gravatar images}
@returns(200) {avatar_url: str} # Return avatar url for a user

@endgroup

@group broadcast_messages
@endpoint GET /broadcast_messages/{id}
@desc Get a specific broadcast message
@required {id: int(int32) # Broadcast message ID}
@returns(200) {id: str, message: str, starts_at: str, ends_at: str, color: str, font: str, target_access_levels: str, target_path: str, broadcast_type: str, dismissable: str, active: str} # Get a specific broadcast message

@endpoint PUT /broadcast_messages/{id}
@desc Update a broadcast message
@required {id: int(int32) # Broadcast message ID}
@optional {message: str # Message to display, starts_at: str(date-time) # Starting time, ends_at: str(date-time) # Ending time, color: str # Background color, font: str # Foreground color, target_access_levels: [int(int32)] # Target user roles, target_path: str # Target path, broadcast_type: str(banner/notification) # Broadcast Type, dismissable: bool # Is dismissable}
@returns(200) {id: str, message: str, starts_at: str, ends_at: str, color: str, font: str, target_access_levels: str, target_path: str, broadcast_type: str, dismissable: str, active: str} # Update a broadcast message

@endpoint DELETE /broadcast_messages/{id}
@desc Delete a broadcast message
@required {id: int(int32) # Broadcast message ID}
@returns(200) {id: str, message: str, starts_at: str, ends_at: str, color: str, font: str, target_access_levels: str, target_path: str, broadcast_type: str, dismissable: str, active: str} # Delete a broadcast message

@endpoint GET /broadcast_messages
@desc Get all broadcast messages
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page}
@returns(200) {id: str, message: str, starts_at: str, ends_at: str, color: str, font: str, target_access_levels: str, target_path: str, broadcast_type: str, dismissable: str, active: str} # Get all broadcast messages

@endpoint POST /broadcast_messages
@desc Create a broadcast message
@required {message: str # Message to display}
@optional {starts_at: str(date-time) # Starting time, ends_at: str(date-time) # Ending time, color: str # Background color, font: str # Foreground color, target_access_levels: [int(int32)] # Target user roles, target_path: str # Target path, broadcast_type: str(banner/notification) # Broadcast type. Defaults to banner, dismissable: bool # Is dismissable}
@returns(201) {id: str, message: str, starts_at: str, ends_at: str, color: str, font: str, target_access_levels: str, target_path: str, broadcast_type: str, dismissable: str, active: str} # Create a broadcast message

@endgroup

@group bulk_imports
@endpoint GET /bulk_imports/{import_id}/entities/{entity_id}
@desc Get GitLab Migration entity details
@required {import_id: int(int32) # The ID of user's GitLab Migration, entity_id: int(int32) # The ID of GitLab Migration entity}
@returns(200) {id: int(int32), bulk_import_id: int(int32), status: str, entity_type: str, source_full_path: str, destination_full_path: str, destination_name: str, destination_slug: str, destination_namespace: str, parent_id: int(int32), namespace_id: int(int32), project_id: int(int32), created_at: str(date-time), updated_at: str(date-time), failures: [map], migrate_projects: bool} # Get GitLab Migration entity details
@errors {401: Unauthorized, 404: Not found, 503: Service unavailable}

@endpoint GET /bulk_imports/{import_id}/entities
@desc List GitLab Migration entities
@required {import_id: int(int32) # The ID of user's GitLab Migration}
@optional {status: str(created/started/finished/timeout/failed) # Return import entities with specified status, page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page}
@returns(200) List GitLab Migration entities
@errors {401: Unauthorized, 404: Not found, 503: Service unavailable}

@endpoint GET /bulk_imports/{import_id}
@desc Get GitLab Migration details
@required {import_id: int(int32) # The ID of user's GitLab Migration}
@returns(200) {id: int(int32), status: str, source_type: str, created_at: str(date-time), updated_at: str(date-time)} # Get GitLab Migration details
@errors {401: Unauthorized, 404: Not found, 503: Service unavailable}

@endpoint GET /bulk_imports/entities
@desc List all GitLab Migrations' entities
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page, sort: str(asc/desc)=desc # Return GitLab Migrations sorted in created by `asc` or `desc` order., status: str(created/started/finished/timeout/failed) # Return all GitLab Migrations' entities with specified status}
@returns(200) List all GitLab Migrations' entities
@errors {401: Unauthorized, 404: Not found, 503: Service unavailable}

@endpoint GET /bulk_imports
@desc List all GitLab Migrations
@optional {page: int(int32)=1 # Current page number, per_page: int(int32)=20 # Number of items per page, sort: str(asc/desc)=desc # Return GitLab Migrations sorted in created by `asc` or `desc` order., status: str(created/started/finished/timeout/failed) # Return GitLab Migrations with specified status}
@returns(200) List all GitLab Migrations
@errors {401: Unauthorized, 404: Not found, 503: Service unavailable}

@endpoint POST /bulk_imports
@desc Start a new GitLab Migration
@returns(200) {id: int(int32), status: str, source_type: str, created_at: str(date-time), updated_at: str(date-time)} # Start a new GitLab Migration
@errors {400: Bad request, 401: Unauthorized, 404: Not found, 422: Unprocessable entity, 503: Service unavailable}

@endgroup

@group application
@endpoint GET /application/appearance
@desc Get the current appearance
@returns(200) {title: str, description: str, pwa_name: str, pwa_short_name: str, pwa_description: str, logo: str, pwa_icon: str, header_logo: str, favicon: str, new_project_guidelines: str, profile_image_guidelines: str, header_message: str, footer_message: str, message_background_color: str, message_font_color: str, email_header_and_footer_enabled: str} # Get the current appearance

@endpoint PUT /application/appearance
@desc Modify appearance
@returns(200) {title: str, description: str, pwa_name: str, pwa_short_name: str, pwa_description: str, logo: str, pwa_icon: str, header_logo: str, favicon: str, new_project_guidelines: str, profile_image_guidelines: str, header_message: str, footer_message: str, message_background_color: str, message_font_color: str, email_header_and_footer_enabled: str} # Modify appearance

@endpoint GET /application/plan_limits
@desc Get current plan limits
@optional {plan_name: str(default/free/bronze/silver/premium/gold/ultimate/ultimate_trial/premium_trial/opensource)=default # Name of the plan to get the limits from. Default: default.}
@returns(200) {ci_pipeline_size: int(int32), ci_active_jobs: int(int32), ci_project_subscriptions: int(int32), ci_pipeline_schedules: int(int32), ci_needs_size_limit: int(int32), ci_registered_group_runners: int(int32), ci_registered_project_runners: int(int32), conan_max_file_size: int(int32), enforcement_limit: int(int32), generic_packages_max_file_size: int(int32), helm_max_file_size: int(int32), limits_history: map, maven_max_file_size: int(int32), notification_limit: int(int32), npm_max_file_size: int(int32), nuget_max_file_size: int(int32), pipeline_hierarchy_size: int(int32), pypi_max_file_size: int(int32), terraform_module_max_file_size: int(int32), storage_size_limit: int(int32)} # Get current plan limits
@errors {401: Unauthorized, 403: Forbidden}

@endpoint PUT /application/plan_limits
@desc Change plan limits
@required {plan_name: str(default/free/bronze/silver/premium/gold/ultimate/ultimate_trial/premium_trial/opensource) # Name of the plan to update}
@optional {ci_pipeline_size: int(int32) # Maximum number of jobs in a single pipeline, ci_active_jobs: int(int32) # Total number of jobs in currently active pipelines, ci_project_subscriptions: int(int32) # Maximum number of pipeline subscriptions to and from a project, ci_pipeline_schedules: int(int32) # Maximum number of pipeline schedules, ci_needs_size_limit: int(int32) # Maximum number of needs dependencies that a job can have, ci_registered_group_runners: int(int32) # Maximum number of runners registered per group, ci_registered_project_runners: int(int32) # Maximum number of runners registered per project, conan_max_file_size: int(int32) # Maximum Conan package file size in bytes, enforcement_limit: int(int32) # Maximum storage size for the root namespace enforcement in MiB, generic_packages_max_file_size: int(int32) # Maximum generic package file size in bytes, helm_max_file_size: int(int32) # Maximum Helm chart file size in bytes, maven_max_file_size: int(int32) # Maximum Maven package file size in bytes, notification_limit: int(int32) # Maximum storage size for the root namespace notifications in MiB, npm_max_file_size: int(int32) # Maximum NPM package file size in bytes, nuget_max_file_size: int(int32) # Maximum NuGet package file size in bytes, pypi_max_file_size: int(int32) # Maximum PyPI package file size in bytes, terraform_module_max_file_size: int(int32) # Maximum Terraform Module package file size in bytes, storage_size_limit: int(int32) # Maximum storage size for the root namespace in MiB, pipeline_hierarchy_size: int(int32) # Maximum number of downstream pipelines in a pipeline's hierarchy tree}
@returns(200) {ci_pipeline_size: int(int32), ci_active_jobs: int(int32), ci_project_subscriptions: int(int32), ci_pipeline_schedules: int(int32), ci_needs_size_limit: int(int32), ci_registered_group_runners: int(int32), ci_registered_project_runners: int(int32), conan_max_file_size: int(int32), enforcement_limit: int(int32), generic_packages_max_file_size: int(int32), helm_max_file_size: int(int32), limits_history: map, maven_max_file_size: int(int32), notification_limit: int(int32), npm_max_file_size: int(int32), nuget_max_file_size: int(int32), pipeline_hierarchy_size: int(int32), pypi_max_file_size: int(int32), terraform_module_max_file_size: int(int32), storage_size_limit: int(int32)} # Change plan limits
@errors {400: Bad request, 401: Unauthorized, 403: Forbidden}

@endgroup

@group metadata
@endpoint GET /metadata
@desc Retrieve metadata information for this GitLab instance
@returns(200) {version: str, revision: str, kas: map{enabled: bool, externalUrl: str, version: str}, enterprise: bool} # Retrieve metadata information for this GitLab instance
@errors {401: Unauthorized}

@endgroup

@group version
@endpoint GET /version
@desc Retrieves version information for the GitLab instance
@returns(200) {version: str, revision: str, kas: map{enabled: bool, externalUrl: str, version: str}, enterprise: bool} # Retrieves version information for the GitLab instance
@errors {401: Unauthorized}

@endgroup

@group projects
@endpoint GET /projects/{id}/jobs
@desc List jobs for a project
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths).}
@optional {scope: [str] # Return all jobs with the specified statuses}
@returns(200) An array of jobs

@endpoint GET /projects/{id}/jobs/{job_id}
@desc Get a single job by ID
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., job_id: int # The ID of the job}
@returns(200) {id: int, name: str, status: str, stage: str, created_at: str(date-time), started_at: str(date-time), finished_at: str(date-time), commit: map{id: str, short_id: str, created_at: str(date-time), parent_ids: [str], title: str, message: str, author_name: str, author_email: str, authored_date: str(date-time), committer_name: str, committer_email: str, committed_date: str(date-time), trailers: map, web_url: str}, archived: bool, allow_failure: bool, erased_at: str(date-time), duration: int, queued_duration: num, ref: str, artifacts: [any], tag: bool, web_url: str, project: map{ci_job_token_scope_enabled: bool}, user: map{id: int(int32), username: str, name: str, state: str, avatar_url: str, avatar_path: str, custom_attributes: [map], web_url: str, email: str}} # A single job object

@endpoint POST /projects/{id}/jobs/{job_id}/play
@desc Run a manual job
@required {id: any # The ID or [URL-encoded path of the project](https://docs.gitlab.com/api/rest/#namespaced-paths)., job_id: int # The ID of the manual job to run}
@optional {job_variables_attributes: [str] # An array containing the custom variables available to the job}
@returns(200) Job started successfully

@endgroup

@end