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"