openapi: 3.0.3 info: title: Develocity Auth TestDistribution 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: TestDistribution x-displayName: Test Distribution description: 'Endpoints related to the management of Test Distribution resources. To access these endpoints the user requires the `Admin` permission. ' paths: /api/test-distribution/agent-pools: get: operationId: ListTestDistributionAgentPools summary: Lists Agent Pools. description: Returns a list of all Agent Pools. tags: - TestDistribution responses: '200': description: The response contains a listing of all Agent Pools. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolPage' example: content: - id: m4yfaq4a name: abc-agents-pool minimumSize: 10 maximumSize: 20 capabilities: - os=linux - jdk=11 - team-abc orderIndex: 1 restrictAccessToProjectGroups: false projectGroupIds: [] - id: dwc4whvi name: def-agents-pool minimumSize: 0 maximumSize: 10 capabilities: - os=windows - jdk=11 orderIndex: 2 restrictAccessToProjectGroups: true projectGroupIds: - project-group-a '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' post: operationId: CreateTestDistributionAgentPool summary: Create an Agent Pool. description: 'Create a new Agent Pool in Develocity. The orderIndex element is optional and can be used to specify the priority order in which the Agent Pool is considered. When not specified, the Agent Pool will be added last. When specified, the Agent Pool will be added at the specified index and all other Agent Pools will be moved down. If the specified index is out of bounds, the Agent Pool will be added last with the orderIndex adjusted accordingly. ' tags: - TestDistribution requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolConfiguration' example: name: abc-agents-pool minimumSize: 10 maximumSize: 20 capabilities: - os=linux - jdk=11 - team-abc orderIndex: 1 restrictAccessToProjectGroups: false projectGroupIds: [] responses: '200': description: A new Agent Pool was created with the configuration specified in the request. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolConfigurationWithId' example: id: m4yfaq4a name: abc-agents-pool minimumSize: 10 maximumSize: 20 capabilities: - os=linux - jdk=11 - team-abc orderIndex: 1 restrictAccessToProjectGroups: false projectGroupIds: [] '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' /api/test-distribution/agent-pools/{poolId}: parameters: - in: path name: poolId example: m4yfaq4a schema: $ref: '#/components/schemas/TestDistributionAgentPoolId' required: true description: The ID of the pool to view. get: operationId: GetTestDistributionAgentPool summary: View the properties of an Agent Pool description: View the identifier, capabilities and size of an Agent Pool. tags: - TestDistribution responses: '200': description: The poolId referenced an existing Agent Pool whose configuration is described in the response. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolConfigurationWithId' example: id: m4yfaq4a name: abc-agents-pool minimumSize: 10 maximumSize: 20 capabilities: - os=linux - jdk=11 - team-abc orderIndex: 1 restrictAccessToProjectGroups: false projectGroupIds: [] '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' put: operationId: CreateOrUpdateTestDistributionAgentPool summary: Create or update an Agent Pool. description: 'Create a new Agent Pool in Develocity or update the configuration of an existing one. The orderIndex element is optional and can be used to specify the priority order in which the Agent Pool is considered. When not specified, the Agent Pool will be either added last on creation, or will not change position on update. When specified, the Agent Pool will be added at/moved to the specified index and all other Agent Pools will be moved down. If the specified index is out of bounds, the Agent Pool will be added last with the orderIndex adjusted accordingly. ' tags: - TestDistribution requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolConfiguration' example: name: abc-agents-pool minimumSize: 10 maximumSize: 20 capabilities: - os=linux - jdk=11 - team-abc orderIndex: 1 restrictAccessToProjectGroups: false projectGroupIds: [] responses: '200': description: The Agent Pool was created or its configuration was updated successfully. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolConfigurationWithId' example: id: m4yfaq4a name: abc-agents-pool minimumSize: 10 maximumSize: 20 capabilities: - os=linux - jdk=11 - team-abc orderIndex: 1 restrictAccessToProjectGroups: false projectGroupIds: [] '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' delete: operationId: DeleteTestDistributionAgentPool summary: Delete an Agent Pool. description: Delete an existing Agent Pool. tags: - TestDistribution responses: '200': description: The poolId referenced an existing Agent Pool and it was deleted. '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' /api/test-distribution/agent-pools/{poolId}/registration-keys: parameters: - in: path name: poolId example: m4yfaq4a schema: $ref: '#/components/schemas/TestDistributionAgentPoolId' required: true description: The ID of the pool to view. get: operationId: ListTestDistributionAgentPoolRegistrationKeys summary: Lists Test Distribution pool-specific agent registration keys. description: Returns a list of all Test Distribution pool-specific agent registration key prefixes. tags: - TestDistribution responses: '200': description: The response contains a listing of the requested type of (active or revoked) Test Distribution pool-specific agent registration key. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolRegistrationKeyPrefixPage' example: content: - keyPrefix: am3mbm5kamztbmrmygym5kamct createdAt: '2021-01-01T12:59:59Z' lastUsedAt: '2021-05-03T10:11:02Z' lastUsedBy: agent1.localhost - keyPrefix: yw3zbwjtnwthbxp3ym6ybxlnew createdAt: '2021-04-20T13:21:43Z' revokedAt: '2022-10-12T11:22:33Z' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' post: operationId: GenerateTestDistributionAgentPoolRegistrationKey summary: Generate a new Test Distribution pool-specific agent registration key. description: Generate a new Test Distribution pool-specific agent registration key to connect agents and query the agent pool API. tags: - TestDistribution requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolRegistrationKeyDescription' example: description: Created by user-x for testing responses: '200': description: A new registration key was successfully generated and contained in the response. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolRegistrationKey' example: key: 46rhyue2hltfwcx36qw7gad74lar4f2clb6a4qo5a433zzx7aqwq description: Created by user-x for testing '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' /api/test-distribution/agent-pools/{poolId}/registration-keys/{keyPrefix}: parameters: - in: path name: poolId example: m4yfaq4a schema: $ref: '#/components/schemas/TestDistributionAgentPoolId' required: true description: The ID of the pool to view. - in: path name: keyPrefix example: riux3fkajs6ivtajxbrunelywk schema: type: string minLength: 26 maxLength: 26 pattern: ^[a-z2-7]{26}$ required: true description: The prefix of the Test Distribution pool-specific agent registration key. get: operationId: GetTestDistributionAgentPoolRegistrationKey summary: Get a Test Distribution pool-specific agent registration keyPrefix information. description: Returns information about a Test Distribution pool-specific agent registration keyPrefix. tags: - TestDistribution responses: '200': description: The response contains information about the requested Test Distribution pool-specific agent registration keyPrefix. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolRegistrationKeyPrefix' example: keyPrefix: am3mbm5kamztbmrmygym5kamct description: Created by user-x for testing createdAt: '2021-01-01T12:59:59Z' lastUsedAt: '2021-05-03T10:11:02Z' lastUsedBy: agent1.localhost '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' put: operationId: InsertTestDistributionAgentPoolRegistrationKey summary: Insert a specific Test Distribution pool-specific agent registration key. description: 'Inserts a specific Test Distribution pool-specific agent registration key to connect agents and query the agent pool API. If a key with the same prefix but different key already exists (regardless of which pool it belongs to), it will return 400. ' tags: - TestDistribution requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolRegistrationKey' example: key: 46rhyue2hltfwcx36qw7gad74lar4f2clb6a4qo5a433zzx7aqwq description: Created by user-x for testing responses: '200': description: The registration key was successfully inserted. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolRegistrationKeyPrefix' example: keyPrefix: am3mbm5kamztbmrmygym5kamct description: Created by user-x for testing createdAt: '2021-01-01T12:59:59Z' lastUsedAt: '2021-05-03T10:11:02Z' lastUsedBy: agent1.localhost '400': $ref: '#/components/responses/BadRequest' '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' delete: operationId: RevokeTestDistributionAgentPoolRegistrationKey summary: Revoke a Test Distribution pool-specific agent registration key. description: 'Revoke the Test Distribution pool-specific agent registration key for the given prefix which uniquely identifies a Test Distribution pool-specific agent registration key. A revoked key can no longer be used to connect agents, but it will still be queryable and returned in the list. ' tags: - TestDistribution responses: '200': description: The registration key was revoked successfully. '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' /api/test-distribution/agent-pools/{poolId}/status: parameters: - in: path name: poolId example: m4yfaq4a schema: $ref: '#/components/schemas/TestDistributionAgentPoolId' required: true description: The ID of the pool to view. get: operationId: GetTestDistributionAgentPoolStatus summary: View the status of an Agent Pool description: 'View the status of an Agent Pool, such as its current size. To access this endpoint the user requires the `Test Distribution` permission. ' tags: - TestDistribution responses: '200': description: The poolId referenced an existing Agent Pool whose status is described in the response. content: application/json: schema: $ref: '#/components/schemas/TestDistributionAgentPoolStatus' example: id: m4yfaq4a name: abc-agents-pool minimumSize: 10 maximumSize: 20 connectedAgents: 15 idleAgents: 5 desiredAgents: 10 '403': $ref: '#/components/responses/ForbiddenError' '404': $ref: '#/components/responses/UnauthorizedOrNotFoundError' components: 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 schemas: TestDistributionAgentPoolId: description: The unique identifier of the agent pool. type: string minLength: 8 maxLength: 8 pattern: ^[a-z2-7]{8}$ TestDistributionAgentPoolStatus: description: The status of an agent pool. type: object required: - id - name - minimumSize - maximumSize - connectedAgents - idleAgents - desiredAgents properties: id: $ref: '#/components/schemas/TestDistributionAgentPoolId' name: type: string description: The alias or display name of the agent pool. minLength: 1 minimumSize: type: integer format: int32 maximumSize: type: integer format: int32 connectedAgents: type: integer format: int32 idleAgents: type: integer format: int32 desiredAgents: type: integer format: int32 TestDistributionAgentPoolConfigurationWithId: description: An agent pool configuration. type: object required: - id - name - minimumSize - maximumSize - capabilities - orderIndex properties: id: $ref: '#/components/schemas/TestDistributionAgentPoolId' name: type: string description: The alias or display name of the agent pool. minLength: 1 example: functional-test-agents minimumSize: type: integer format: int32 minimum: 0 maximumSize: type: integer format: int32 minimum: 0 orderIndex: description: The order in which the agent pool is considered for allocation. Lower values are considered first. type: integer format: int32 minimum: 0 capabilities: type: array items: type: string pattern: ^([-\w.]+)(?:=([-\w.]+))?$ example: - jdk=17 - os=linux - functional-test restrictAccessToProjectGroups: type: boolean description: 'Controls whether this pool can be used by everyone, or only the assigned project groups. A `true` value implies that `projectGroupIds` is present and has at least one entry. Conversely, a `false` value implies that `projectGroupIds` is empty. ' default: false projectGroupIds: type: array description: 'Controls which project groups can use this pool. If it is empty, then `restrictAccessToProjectGroups` must be `false`. Conversely, if it has values then `restrictAccessToProjectGroups` must be `true`. ' items: type: string pattern: ^[^\\s]{1,215}$ example: project-group-a TestDistributionAgentPoolRegistrationKey: description: A Test Distribution pool-specific agent registration key. type: object required: - key properties: key: type: string minLength: 52 maxLength: 52 pattern: ^[a-z2-7]{52}$ description: The agent API key. description: type: string maxLength: 100 description: Description of the registration key to help identify it later. example: Used by xyz TestDistributionAgentPoolRegistrationKeyPrefix: description: A Test Distribution pool-specific agent registration key prefix. type: object required: - keyPrefix - createdAt properties: keyPrefix: type: string minLength: 26 maxLength: 26 pattern: ^[a-z2-7]{26}$ description: The registration key prefix. description: type: string maxLength: 100 description: Description of the registration key to help identify it later. example: Used by xyz createdAt: type: string format: date-time description: When the key was created lastUsedAt: type: string format: date-time nullable: true description: When the key was last used lastUsedBy: type: string nullable: true description: Who used the key last revokedAt: type: string format: date-time nullable: true description: When the key was revoked, a non-null value implies that the key is revoked and can no longer be used to authenticate. TestDistributionAgentPoolConfiguration: description: An agent pool configuration. type: object required: - name - minimumSize - maximumSize - capabilities properties: name: type: string description: The alias or display name of the agent pool. minLength: 1 example: functional-test-agents minimumSize: type: integer format: int32 minimum: 0 maximumSize: type: integer format: int32 minimum: 0 orderIndex: description: The order in which the agent pool is considered for allocation. Lower values are considered first. type: integer format: int32 nullable: true minimum: 0 capabilities: type: array items: type: string pattern: ^([-\w.]+)(?:=([-\w.]+))?$ example: - jdk=17 - os=linux - functional-test restrictAccessToProjectGroups: type: boolean description: 'Controls whether this pool can be used by everyone, or only the assigned project groups. A `true` value implies that `projectGroupIds` is present and has at least one entry. Conversely, a `false` value implies that `projectGroupIds` is empty. ' default: false projectGroupIds: type: array description: 'Controls which project groups can use this pool. If it is empty, then `restrictAccessToProjectGroups` must be `false`. Conversely, if it has values then `restrictAccessToProjectGroups` must be `true`. ' items: type: string pattern: ^[^\\s]{1,215}$ example: project-group-a TestDistributionAgentPoolRegistrationKeyPrefixPage: description: A list of Test Distribution pool-specific agent registration key prefixes. type: object required: - content properties: content: type: array items: $ref: '#/components/schemas/TestDistributionAgentPoolRegistrationKeyPrefix' TestDistributionAgentPoolPage: description: A list of agent pools. type: object required: - content properties: content: type: array description: A list of agent pool IDs. items: $ref: '#/components/schemas/TestDistributionAgentPoolConfigurationWithId' TestDistributionAgentPoolRegistrationKeyDescription: description: Optional description of a Test Distribution pool-specific agent registration key. type: object properties: description: type: string maxLength: 100 description: Description of the registration key to help identify it later. example: Used by xyz 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 responses: 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. 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' securitySchemes: DevelocityAccessKeyOrToken: type: http scheme: bearer bearerFormat: Bearer <> 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"