Use the Components API to create, retrieve, update, and delete components programmatically, including creating a component directly from a repository URL without first configuring an SCM integration. For the field-level reference and the upgrade behavior, refer to Create components without SCM integration.
Example requests and responses are provided below to help you get started.
All requests require a personal access token in the Authorization: Bearer header.
To generate one, refer to Manage personal access tokens.
|
| To retrieve your organization ID, refer to Locate organization ID. |
Example: Create a component
Create a component from a repository URL.
If you omit integrationId, CloudBees Unify automatically attaches an existing SCM integration that has access to the repository.
If no such integration exists, CloudBees Unify creates the component without an SCM integration.
curl -L 'https://api.cloudbees.io/v4/organizations/<organization_id>/components' \ --request POST \ --header 'Authorization: Bearer <personal_access_token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "payments-service", "repositoryUrl": "https://github.com/example/payments-service.git" }'
{ "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "payments-service", "description": "", "repositoryUrl": "https://github.com/example/payments-service.git", "repositoryHref": "https://github.com/example/payments-service", "defaultBranch": "main", "provider": "GITHUB", "integrationId": "", "organizationId": "<organization_id>", "createdAt": "2026-10-16T09:00:00Z", "updatedAt": "2026-10-16T09:00:00Z" }
This is the complete set of fields on a component.
Example: List and filter components
List components in an organization, optionally filtered by name, repositoryUrl, or provider.
curl -L 'https://api.cloudbees.io/v4/organizations/<organization_id>/components?repositoryUrl=https://github.com/example/payments-service.git' \ --header 'Authorization: Bearer <personal_access_token>'
{ "components": [ { "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "payments-service", "repositoryUrl": "https://github.com/example/payments-service.git", "provider": "GITHUB" } ], "nextPageToken": "", "totalSize": 1 }
Each entry in components is a full component object.
| The response includes every field on the component, not just the ones shown here. Only the fields relevant to this example are shown for brevity — refer to the create example for the complete object. |
Example: Retrieve a single component
curl -L 'https://api.cloudbees.io/v4/organizations/<organization_id>/components/<component_id>' \ --header 'Authorization: Bearer <personal_access_token>'
{ "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "payments-service", "repositoryUrl": "https://github.com/example/payments-service.git", "defaultBranch": "main", "provider": "GITHUB", "integrationId": "" }
| The response includes every field on the component, not just the ones shown here. Only the fields relevant to this example are shown for brevity — refer to the create example for the complete object. |
Example: Update a component
Update only the fields you include in the request body.
curl -L 'https://api.cloudbees.io/v4/organizations/<organization_id>/components/<component_id>' \ --request PATCH \ --header 'Authorization: Bearer <personal_access_token>' \ --header 'Content-Type: application/json' \ --data '{ "defaultBranch": "develop" }'
{ "id": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "name": "payments-service", "defaultBranch": "develop" }
| The response includes every field on the component, not just the ones shown here. Only the fields relevant to this example are shown for brevity — refer to the create example for the complete object. |
Example: Delete a component
curl -L 'https://api.cloudbees.io/v4/organizations/<organization_id>/components/<component_id>' \ --request DELETE \ --header 'Authorization: Bearer <personal_access_token>'
{ "success": true, "message": "Component deleted successfully." }
|
Deleting a component is irreversible. |
Example end-to-end use case, onboard a component without SCM and upgrade it later
This example shows how to onboard a component with no SCM integration, start reporting pipeline data to it, and let it upgrade automatically once an SCM integration is configured later.
You can use these endpoints to:
Step 1: Create the component without an SCM integration
Omit integrationId and provider is inferred from the repository URL.
curl -L 'https://api.cloudbees.io/v4/organizations/<organization_id>/components' \ --request POST \ --header 'Authorization: Bearer <personal_access_token>' \ --header 'Content-Type: application/json' \ --data '{ "name": "legacy-billing", "repositoryUrl": "https://gerrit.example.com/legacy-billing.git", "provider": "GERRIT" }'
{ "id": "f1e2d3c4-b5a6-4978-8c6d-5e4f3a2b1c0d", "name": "legacy-billing", "repositoryUrl": "https://gerrit.example.com/legacy-billing.git", "provider": "GERRIT", "integrationId": "" }
| The response includes every field on the component, not just the ones shown here. Only the fields relevant to this example are shown for brevity — refer to the create example for the complete object. |
Step 2: Report a pipeline run against the component
With no SCM integration, CloudBees Unify only tracks pipeline data when an external CI/CD tool reports it directly, using the Run APIs.
curl -L 'https://api.cloudbees.io/v4/components/f1e2d3c4-b5a6-4978-8c6d-5e4f3a2b1c0d/runs' \ --request POST \ --header 'Authorization: Bearer <personal_access_token>' \ --header 'Content-Type: application/json' \ --data '{ "scmRef": "refs/heads/main", "workflowName": "build-and-test", "toolType": "JENKINS", "url": "https://ci.example.com/jobs/build-and-test/42", "trigger": "PUSH", "actorName": "jane.doe", "status": "SUCCEEDED", "startedAt": "2026-10-16T09:05:00Z", "commitSha": "1234abcd5678ef90" }'
{ "runId": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d" }
Step 3: Confirm the automatic upgrade after configuring an SCM integration
After you configure an SCM integration that has access to the legacy-billing repository, CloudBees Unify attaches it automatically.
Retrieve the component again to confirm integrationId is now populated, with no manual steps required.
curl -L 'https://api.cloudbees.io/v4/organizations/<organization_id>/components/f1e2d3c4-b5a6-4978-8c6d-5e4f3a2b1c0d' \ --header 'Authorization: Bearer <personal_access_token>'
{ "id": "f1e2d3c4-b5a6-4978-8c6d-5e4f3a2b1c0d", "integrationId": "9c8b7a6d-5e4f-4a3b-2c1d-0e9f8a7b6c5d" }
Everything else on the component is unchanged from Step 1: Create the component without an SCM integration.
| The response includes every field on the component, not just the ones shown here. Only the fields relevant to this example are shown for brevity — refer to the create example for the complete object. |