Endpoints related to the management of project-level access control in Develocity. To access these endpoints the user requires the `Administer Projects` permission. **Beta: _The Projects API is unstable and is likely to change in future._**
openapi: 3.0.3
info:
title: Develocity Auth Projects API
description: 'The Develocity API allows programmatic interaction with various aspects of Develocity, from configuration to inspecting build data.
'
version: 2026.2.0
license:
name: Develocity License
url: https://gradle.com/help/legal-gradle-software-license-agreement
termsOfService: https://gradle.com/help/legal-terms-of-use
contact:
name: Gradle
url: https://gradle.com
x-logo:
url: https://assets.gradle.com/logo/develocity-logo.svg
altText: Develocity
servers:
- url: https://develocity.example.com
description: Your Develocity instance.
security:
- DevelocityAccessKeyOrToken: []
tags:
- name: Projects
x-displayName: 'Projects (Beta)
'
description: 'Endpoints related to the management of project-level access control in Develocity.
To access these endpoints the user requires the `Administer Projects` permission.
**<mark>Beta:</mark> _The Projects API is unstable and is likely to change in future._**
'
paths:
/api/project-groups:
get:
operationId: ListProjectGroups
summary: Lists access control project groups.
description: '**<mark>Beta:</mark>** Returns a list of all project groups configured for project-level access control.
If there are a lot of project groups, then all pages will need to be retrieved in order to retrieve the full list of project groups.
The default number of project groups per page is 100.
'
tags:
- Projects
parameters:
- in: query
name: PageQuery
explode: true
description: The page to fetch.
schema:
$ref: '#/components/schemas/PageQuery'
responses:
'200':
description: A list of project groups configured for project-level access control.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectGroupsPage'
example:
content:
- id: some-project-group
displayName: Some Project Group
description: An example project group
projects:
- id: some-project
- id: another-project
- id: another-project-group
displayName: Another Project Group
description: Another example project group
projects:
- id: another-project
page:
number: 1
size: 50
totalPages: 4
totalElements: 151
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/UnauthorizedOrNotFoundError'
/api/project-groups/{projectGroupId}:
parameters:
- in: path
name: projectGroupId
example: a-project-group
schema:
$ref: '#/components/schemas/ProjectGroupId'
required: true
description: The ID of the project group configured for project-level access control.
get:
operationId: GetProjectGroup
summary: Get an access control project group.
description: '**<mark>Beta:</mark>** Gets a specific project group configured for project-level access control.
'
tags:
- Projects
responses:
'200':
description: The requested project group configured for project-level access control.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectGroup'
example:
id: some-project-group
displayName: Some Project Group
description: An example project group
projects:
- id: some-project
- id: another-project
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/UnauthorizedOrNotFoundError'
put:
operationId: CreateOrUpdateProjectGroup
summary: Create or update an access control project group.
description: '**<mark>Beta:</mark>** Create or update a project group configured for project-level access control in Develocity.
When updating, any optional fields that are omitted from the request, but were previously set on the project group, will be unset/removed.
An existing project group''s identifier cannot be updated.
If the update contains a id that does not match the current id, then the operation will fail with a Bad Request response.
'
tags:
- Projects
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectGroup'
example:
id: some-project-group
displayName: Some Project Group
description: An example project group
projects:
- id: some-project
- id: another-project
responses:
'200':
description: The project group was created or updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectGroup'
example:
id: some-project-group
displayName: Some Project Group
description: An example project group
projects:
- id: some-project
- id: another-project
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/UnauthorizedOrNotFoundError'
delete:
operationId: DeleteProjectGroup
summary: Delete an access control project group.
description: '**<mark>Beta:</mark>** Delete a project group configured for project-level access control in Develocity.
'
tags:
- Projects
responses:
'200':
description: The projectId referenced an existing project group and it was deleted.
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/UnauthorizedOrNotFoundError'
/api/projects:
get:
operationId: ListProjects
summary: Lists access control projects.
description: '**<mark>Beta:</mark>** Returns a paged list of projects configured for project-level access control.
If there are a lot of projects, then all pages will need to be retrieved in order to retrieve the full list of projects.
The default number of projects per page is 1,000.
'
tags:
- Projects
parameters:
- in: query
name: PageQuery
explode: true
description: The page to fetch.
schema:
$ref: '#/components/schemas/PageQuery'
responses:
'200':
description: A list of projects configured for project-level access control in Develocity.
content:
application/json:
schema:
$ref: '#/components/schemas/ProjectsPage'
example:
content:
- id: some-project
displayName: Some Project
description: An example project
- id: another-project
displayName: Another Project
description: Another example project
page:
number: 1
size: 100
totalPages: 4
totalElements: 351
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/UnauthorizedOrNotFoundError'
/api/projects/{projectId}:
parameters:
- in: path
name: projectId
example: a-project
schema:
$ref: '#/components/schemas/ProjectId'
required: true
description: The ID of the access control project.
get:
operationId: GetProject
summary: Get an access control project.
description: '**<mark>Beta:</mark>** Gets a specific project configured for project-level access control.
'
tags:
- Projects
responses:
'200':
description: The requested project configured for project-level access control.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
example:
id: some-project
displayName: Some Project
description: An example project
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/UnauthorizedOrNotFoundError'
put:
operationId: CreateOrUpdateProject
summary: Create or update an access control project.
description: '**<mark>Beta:</mark>** Create or update a project configured for project-level access control in Develocity.
When updating, any optional fields that are omitted from the request, but were previously set on the project, will be unset/removed.
An existing project''s identifier cannot be updated.
If the update contains a id that does not match the current id, then the operation will fail with a Bad Request response.
'
tags:
- Projects
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
example:
id: some-project
displayName: Some Project
description: An example project
responses:
'200':
description: The project was created or updated successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Project'
example:
id: some-project
displayName: Some Project
description: An example project
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/ForbiddenError'
'404':
$ref: '#/components/responses/UnauthorizedOrNotFoundError'
components:
schemas:
ProjectsPage:
type: object
description: A paged list of projects configured for project-level access control in Develocity.
required:
- content
- page
properties:
content:
type: array
description: A list of projects configured for project-level access control in Develocity.
items:
$ref: '#/components/schemas/Project'
page:
$ref: '#/components/schemas/PageMetadata'
PageQuery:
type: object
properties:
pageNumber:
type: integer
format: int32
description: 'The index of the page to retrieve.
The first page''s index is zero.
'
minimum: 0
default: 0
pageSize:
type: integer
format: in32
description: The maximum number of elements to include in the fetched page.
minimum: 0
ProjectGroupsPage:
type: object
description: A paged list of project groups configured for project-level access control in Develocity.
required:
- content
- page
properties:
content:
type: array
description: A list of project groups configured for project-level access control in Develocity.
items:
$ref: '#/components/schemas/ProjectGroup'
page:
$ref: '#/components/schemas/PageMetadata'
ProjectGroup:
type: object
description: A group of projects that can be assigned to users.
required:
- id
properties:
id:
$ref: '#/components/schemas/ProjectGroupId'
displayName:
type: string
description: The label used when displaying the project group.
maxLength: 266
description:
type: string
description: The description of the project group.
maxLength: 1024
identityProviderAttributeValue:
type: string
description: 'The value of an identity provider attribute this project group is associated with.
Users who have this value in the identity provider attribute will be assigned this project group.
'
minLength: 1
maxLength: 256
projects:
type: array
items:
$ref: '#/components/schemas/ProjectReference'
Project:
type: object
description: A project configured for project-level access control in Develocity.
required:
- id
properties:
id:
$ref: '#/components/schemas/ProjectId'
displayName:
type: string
description: The label used when displaying the project.
maxLength: 266
description:
type: string
description: The description of the project group.
maxLength: 1024
ProjectReference:
type: object
description: A container for a project ID.
required:
- id
properties:
id:
$ref: '#/components/schemas/ProjectId'
PageMetadata:
type: object
description: 'Information about the current and available page of elements.
Pages are returned from list operations which could contain a lot of elements.
One page contains a subset of the available elements.
API users can retrieve all pages in order to retrieve all of the available elements.
'
required:
- number
- size
- totalElements
- totalPages
properties:
number:
type: integer
format: int32
description: The index of the current page. Page indexes start at zero.
minimum: 0
size:
type: integer
format: int32
description: The number of elements in the current page.
minimum: 0
totalPages:
type: integer
format: int32
description: The total number of pages.
minimum: 0
totalElements:
type: integer
format: int32
description: The total number of elements across all pages.
minimum: 0
ProjectGroupId:
type: string
description: The unique identifier for the project group configured for project-level access control in Develocity. Must not contain whitespace.
minLength: 1
maxLength: 215
pattern: ^\S+$
ProjectId:
type: string
description: The unique identifier for the project. Must not contain whitespace.
minLength: 1
maxLength: 256
pattern: ^\S+$
ApiProblem:
type: object
description: 'Response detailing why a request was rejected.
Adheres to the [RFC-7807](https://datatracker.ietf.org/doc/html/rfc7807) standard (colloquially known as "Problem JSON") for the response format.
'
required:
- type
- title
- status
properties:
status:
type: integer
description: HTTP status code of the problem response.
type:
type: string
description: A URN (Uniform Resource Name) identifying the type of the problem.
title:
type: string
description: The underlying reason for the problem.
detail:
type: string
description: A longer and comprehensive description of the problem. May be `null` if not available.
nullable: true
examples:
ForbiddenUserExample:
value:
type: urn:gradle:enterprise:forbidden
title: Insufficient permissions
detail: User must have the Administer Projects permission to access this endpoint.
status: 403
CapabilityValidationProblemExample:
value:
type: urn:gradle:enterprise:validation
title: Invalid request parameters
detail: One or more capabilities have an invalid format.
status: 400
responses:
BadRequest:
description: The request body is malformed or contains invalid values for at least one of the properties.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ApiProblem'
examples:
CapabilityValidationProblemResponse:
$ref: '#/components/examples/CapabilityValidationProblemExample'
ForbiddenError:
description: The authenticated user has insufficient permissions.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ApiProblem'
examples:
ForbiddenUserResponse:
$ref: '#/components/examples/ForbiddenUserExample'
UnauthorizedOrNotFoundError:
description: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.
securitySchemes:
DevelocityAccessKeyOrToken:
type: http
scheme: bearer
bearerFormat: Bearer <<Develocity Access Key or Token>>
description: "All requests require a Develocity access key or token as a bearer token. \nGiven an access key of `l3an7wk3j4ze5v4mi7rvgjf2p7g44nvlswg4cpvdonjs7rzd4kmq`, the required header is `Authorization: Bearer l3an7wk3j4ze5v4mi7rvgjf2p7g44nvlswg4cpvdonjs7rzd4kmq`.\n\nPlease consult the [Develocity API User Manual](https://gradle.com/help/api-access-control) for guidance on how to provision access keys or tokens and check user permissions.\n"