# Release Candidates

## GET /sfp/api/release-candidates

> List release candidates with optional filters

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates":{"get":{"operationId":"ReleaseCandidatesController_listReleaseCandidates","summary":"List release candidates with optional filters","parameters":[{"name":"repositoryIdentifier","required":false,"in":"query","description":"Filter by repository identifier (e.g., flxbl-io/sf-core)","schema":{"type":"string"}},{"name":"domain","required":false,"in":"query","description":"Filter by domain (e.g., core, auth, origination)","schema":{"type":"string"}},{"name":"branch","required":false,"in":"query","description":"Filter by branch (e.g., main, develop)","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Limit results (1-200, default: 50)","schema":{"type":"number"}},{"name":"offset","required":false,"in":"query","description":"Offset for pagination (default: 0)","schema":{"type":"number"}}],"responses":{"200":{"description":"List of release candidates","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"description":"List of release candidates","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier"},"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"domain":{"type":"string","description":"Domain/release configuration name"},"releaseName":{"type":"string","description":"Release name"},"commitSha":{"type":"string","description":"Git commit SHA"},"branch":{"type":"string","description":"Git branch name"},"tag":{"type":"string","description":"Git tag"},"value":{"type":"object","description":"Release definition and metadata"},"version":{"type":"number","description":"Version number"},"createdAt":{"type":"string","description":"Creation timestamp"},"updatedAt":{"type":"string","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by (email or \"application\")"},"updatedBy":{"type":"string","description":"Updated by (email or \"application\")"}},"required":["id","repositoryIdentifier","domain","releaseName","commitSha","value","version","createdAt","updatedAt","createdBy","updatedBy"]}},"total":{"type":"number","description":"Total count of release candidates"},"limit":{"type":"number","description":"Number of items returned"},"offset":{"type":"number","description":"Offset for pagination"}},"required":["items","total","limit","offset"]}}}},"400":{"description":"Bad request"}},"tags":["release-candidates"]}}}}
```

## POST /sfp/api/release-candidates

> Create or update a release candidate

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates":{"post":{"operationId":"ReleaseCandidatesController_createReleaseCandidate","summary":"Create or update a release candidate","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., \"owner/repo\")"},"domain":{"type":"string","description":"Domain/release configuration name"},"releaseName":{"type":"string","description":"Release name"},"commitSha":{"type":"string","description":"Git commit SHA"},"branch":{"type":"string","description":"Git branch name"},"tag":{"type":"string","description":"Git tag"},"value":{"type":"object","description":"Release definition and metadata"}},"required":["repositoryIdentifier","domain","releaseName","commitSha","value"]}}}},"responses":{"201":{"description":"Release candidate created/updated","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier"},"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"domain":{"type":"string","description":"Domain/release configuration name"},"releaseName":{"type":"string","description":"Release name"},"commitSha":{"type":"string","description":"Git commit SHA"},"branch":{"type":"string","description":"Git branch name"},"tag":{"type":"string","description":"Git tag"},"value":{"type":"object","description":"Release definition and metadata"},"version":{"type":"number","description":"Version number"},"createdAt":{"type":"string","description":"Creation timestamp"},"updatedAt":{"type":"string","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by (email or \"application\")"},"updatedBy":{"type":"string","description":"Updated by (email or \"application\")"}},"required":["id","repositoryIdentifier","domain","releaseName","commitSha","value","version","createdAt","updatedAt","createdBy","updatedBy"]}}}},"400":{"description":"Bad request"},"409":{"description":"Conflict - version mismatch"}},"tags":["release-candidates"]}}}}
```

## GET /sfp/api/release-candidates/latest

> Get the latest release candidate for a domain

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates/latest":{"get":{"operationId":"ReleaseCandidatesController_getLatestReleaseCandidate","summary":"Get the latest release candidate for a domain","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (e.g., flxbl-io/sf-core)","schema":{"type":"string"}},{"name":"domain","required":true,"in":"query","description":"Domain name (e.g., core, auth, origination)","schema":{"type":"string"}},{"name":"branch","required":false,"in":"query","description":"Filter by branch (e.g., main, develop)","schema":{"type":"string"}}],"responses":{"200":{"description":"Latest release candidate","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier"},"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"domain":{"type":"string","description":"Domain/release configuration name"},"releaseName":{"type":"string","description":"Release name"},"commitSha":{"type":"string","description":"Git commit SHA"},"branch":{"type":"string","description":"Git branch name"},"tag":{"type":"string","description":"Git tag"},"value":{"type":"object","description":"Release definition and metadata"},"version":{"type":"number","description":"Version number"},"createdAt":{"type":"string","description":"Creation timestamp"},"updatedAt":{"type":"string","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by (email or \"application\")"},"updatedBy":{"type":"string","description":"Updated by (email or \"application\")"}},"required":["id","repositoryIdentifier","domain","releaseName","commitSha","value","version","createdAt","updatedAt","createdBy","updatedBy"]}}}},"404":{"description":"No release candidates found"}},"tags":["release-candidates"]}}}}
```

## GET /sfp/api/release-candidates/{id}

> Get a specific release candidate

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates/{id}":{"get":{"operationId":"ReleaseCandidatesController_getReleaseCandidate","summary":"Get a specific release candidate","parameters":[{"name":"id","required":true,"in":"path","description":"Release candidate ID","schema":{"type":"string"}}],"responses":{"200":{"description":"Release candidate details","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier"},"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"domain":{"type":"string","description":"Domain/release configuration name"},"releaseName":{"type":"string","description":"Release name"},"commitSha":{"type":"string","description":"Git commit SHA"},"branch":{"type":"string","description":"Git branch name"},"tag":{"type":"string","description":"Git tag"},"value":{"type":"object","description":"Release definition and metadata"},"version":{"type":"number","description":"Version number"},"createdAt":{"type":"string","description":"Creation timestamp"},"updatedAt":{"type":"string","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by (email or \"application\")"},"updatedBy":{"type":"string","description":"Updated by (email or \"application\")"}},"required":["id","repositoryIdentifier","domain","releaseName","commitSha","value","version","createdAt","updatedAt","createdBy","updatedBy"]}}}},"404":{"description":"Release candidate not found"}},"tags":["release-candidates"]}}}}
```

## DELETE /sfp/api/release-candidates/{id}

> Delete a release candidate

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates/{id}":{"delete":{"operationId":"ReleaseCandidatesController_deleteReleaseCandidate","summary":"Delete a release candidate","parameters":[{"name":"id","required":true,"in":"path","description":"Release candidate ID","schema":{"type":"string"}}],"responses":{"204":{"description":"Release candidate deleted"},"404":{"description":"Release candidate not found"}},"tags":["release-candidates"]}}}}
```

## POST /sfp/api/release-candidates/{id}/compare

> Compare release candidate with an environment

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates/{id}/compare":{"post":{"operationId":"ReleaseCandidatesController_compareWithEnvironment","summary":"Compare release candidate with an environment","parameters":[{"name":"id","required":true,"in":"path","description":"Release candidate ID","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"environmentId":{"type":"string","description":"Environment ID to compare against"}},"required":["environmentId"]}}}},"responses":{"200":{"description":"Comparison results","content":{"application/json":{"schema":{"type":"object","properties":{"releaseCandidate":{"description":"Release candidate being compared","allOf":[{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier"},"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"domain":{"type":"string","description":"Domain/release configuration name"},"releaseName":{"type":"string","description":"Release name"},"commitSha":{"type":"string","description":"Git commit SHA"},"branch":{"type":"string","description":"Git branch name"},"tag":{"type":"string","description":"Git tag"},"value":{"type":"object","description":"Release definition and metadata"},"version":{"type":"number","description":"Version number"},"createdAt":{"type":"string","description":"Creation timestamp"},"updatedAt":{"type":"string","description":"Last update timestamp"},"createdBy":{"type":"string","description":"Created by (email or \"application\")"},"updatedBy":{"type":"string","description":"Updated by (email or \"application\")"}},"required":["id","repositoryIdentifier","domain","releaseName","commitSha","value","version","createdAt","updatedAt","createdBy","updatedBy"]}]},"environment":{"type":"object","description":"Environment being compared against"},"comparison":{"type":"object","description":"Comparison results","properties":{"packagesToInstall":{"type":"array","items":{"$ref":"#/components/schemas/PackageComparisonDto"}},"packagesToUpdate":{"type":"array","items":{"$ref":"#/components/schemas/PackageComparisonDto"}},"packagesToRemove":{"type":"array","items":{"$ref":"#/components/schemas/PackageComparisonDto"}},"totalChanges":{"type":"number"}}},"estimatedDeploymentTime":{"type":"number","description":"Estimated deployment time in minutes"}},"required":["releaseCandidate","environment","comparison","estimatedDeploymentTime"]}}}},"404":{"description":"Release candidate or environment not found"}},"tags":["release-candidates"]}}}}
```

## GET /sfp/api/release-candidates/{id}/changes

> Get change analysis for a release candidate

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates/{id}/changes":{"get":{"operationId":"ReleaseCandidatesController_getChangeAnalysis","summary":"Get change analysis for a release candidate","parameters":[{"name":"id","required":true,"in":"path","description":"Release candidate ID","schema":{"type":"string"}},{"name":"since","required":false,"in":"query","description":"Compare changes since this commit SHA or date","schema":{"type":"string"}}],"responses":{"200":{"description":"Change analysis","content":{"application/json":{"schema":{"type":"object","properties":{"packages":{"description":"Package changes","type":"array","items":{"type":"string"}},"workItems":{"description":"Work items extracted from commits","type":"array","items":{"type":"string"}},"commits":{"description":"Commit information","type":"array","items":{"type":"string"}}},"required":["packages","workItems","commits"]}}}},"404":{"description":"Release candidate not found"}},"tags":["release-candidates"]}}}}
```

## Get rolling analysis from baseline to latest candidate

> Performs comprehensive rolling analysis showing progression from last completed release to latest candidate

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates/rolling-analysis/{repository}/{domain}":{"get":{"operationId":"ReleaseCandidatesController_getRollingAnalysis","summary":"Get rolling analysis from baseline to latest candidate","description":"Performs comprehensive rolling analysis showing progression from last completed release to latest candidate","parameters":[{"name":"repository","required":true,"in":"path","description":"Repository identifier (e.g., flxbl-io/sf-core)","schema":{"type":"string"}},{"name":"domain","required":true,"in":"path","description":"Domain name (e.g., core, auth, origination)","schema":{"type":"string"}},{"name":"branch","required":false,"in":"query","description":"Filter by branch (e.g., main, develop)","schema":{"type":"string"}},{"name":"includeChangelog","required":false,"in":"query","description":"Include package changelogs (default: false)","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Rolling analysis data","content":{"application/json":{"schema":{"type":"object","properties":{"repository":{"type":"string","description":"Repository identifier"},"domain":{"type":"string","description":"Domain name"},"baseline":{"description":"Baseline release information","allOf":[{"type":"object","properties":{"releaseName":{"type":"string","description":"Release name"},"createdAt":{"type":"string","description":"When the baseline release candidate was created"},"completedAt":{"type":"string","description":"When the release was completed/deployed"},"deployedEnvironments":{"description":"Environments where this release is fully deployed","type":"array","items":{"type":"string"}},"packages":{"type":"object","description":"Package versions in this release","additionalProperties":{"type":"string"}}},"required":["releaseName","createdAt","completedAt","deployedEnvironments","packages"]}]},"orchestrationOrder":{"description":"Environment orchestration order","type":"array","items":{"type":"string"}},"currentEnvironmentStates":{"type":"object","description":"Current state of each environment","additionalProperties":{"type":"object","properties":{"currentRelease":{"type":"string","nullable":true},"packages":{"type":"object","additionalProperties":{"type":"string"}}}}},"candidates":{"description":"All candidates from baseline to latest (deprecated: use candidatesByBranch for branch-grouped data)","deprecated":true,"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Candidate ID"},"releaseName":{"type":"string","description":"Release name"},"branch":{"type":"string","description":"Git branch"},"commitSha":{"type":"string","description":"Git commit SHA"},"createdAt":{"type":"string","description":"Creation timestamp"},"incrementalChanges":{"description":"Changes from previous candidate","allOf":[{"type":"object","properties":{"packages":{"description":"Package changes","allOf":[{"type":"object","properties":{"added":{"type":"array","description":"Added packages","items":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}}},"updated":{"type":"array","description":"Updated packages","items":{"type":"object","properties":{"name":{"type":"string"},"fromVersion":{"type":"string"},"toVersion":{"type":"string"}}}},"removed":{"type":"array","description":"Removed packages","items":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"}}}}},"required":["added","updated","removed"]}]},"summary":{"type":"object","description":"Summary metrics","properties":{"totalPackageChanges":{"type":"number"},"totalCommits":{"type":"number"},"totalWorkItems":{"type":"number"}}}},"required":["packages","summary"]}]},"cumulativeChanges":{"description":"Total changes from baseline","allOf":[{"type":"object","properties":{"packages":{"description":"Package changes","allOf":[{"type":"object","properties":{"$ref":"#/paths/~1sfp~1api~1release-candidates~1rolling-analysis~1{repository}~1{domain}/get/responses/200/content/application~1json/schema/properties/candidates/items/properties/incrementalChanges/allOf/0/properties/packages/allOf/0/properties"},"required":["added","updated","removed"]}]},"summary":{"type":"object","description":"Summary metrics","properties":{"totalPackageChanges":{"type":"number"},"totalCommits":{"type":"number"},"totalWorkItems":{"type":"number"}}},"cumulativeSummary":{"type":"object","description":"Additional cumulative metrics","properties":{"estimatedDeploymentTime":{"type":"number","description":"Estimated time in minutes"}}}},"required":["packages","summary","cumulativeSummary"]}]}},"required":["id","releaseName","commitSha","createdAt","incrementalChanges","cumulativeChanges"]}},"candidatesByBranch":{"description":"Candidates grouped by branch","allOf":[{"type":"object","properties":{"byBranch":{"type":"object","description":"Candidates grouped by branch","additionalProperties":{"type":"array","items":{"type":"object","properties":{"$ref":"#/paths/~1sfp~1api~1release-candidates~1rolling-analysis~1{repository}~1{domain}/get/responses/200/content/application~1json/schema/properties/candidates/items/properties"},"required":["id","releaseName","commitSha","createdAt","incrementalChanges","cumulativeChanges"]}}},"all":{"description":"Flat list of all candidates (for backward compatibility)","type":"array","items":{"type":"object","properties":{"$ref":"#/paths/~1sfp~1api~1release-candidates~1rolling-analysis~1{repository}~1{domain}/get/responses/200/content/application~1json/schema/properties/candidates/items/properties"},"required":["id","releaseName","commitSha","createdAt","incrementalChanges","cumulativeChanges"]}}},"required":["byBranch","all"]}]},"summary":{"description":"Comprehensive analysis summary","allOf":[{"type":"object","properties":{"deploymentPipeline":{"description":"Deployment pipeline state","allOf":[{"type":"object","properties":{"environmentStatus":{"description":"Status of each environment","type":"array","items":{"type":"object","properties":{"environment":{"type":"string","description":"Environment name"},"currentRelease":{"type":"string","description":"Currently deployed release"},"candidatesInQueue":{"description":"Release candidates queued for this environment","type":"array","items":{"type":"string"}}},"required":["environment","candidatesInQueue"]}},"blockers":{"description":"Identified blockers","type":"array","items":{"type":"object","properties":{"environment":{"type":"string","description":"Blocked environment"},"blockedCandidate":{"type":"string","description":"Blocked candidate release name"},"reason":{"type":"string","description":"Reason for blockage"}},"required":["environment","blockedCandidate","reason"]}}},"required":["environmentStatus"]}]},"progressMetrics":{"description":"Progress tracking metrics","allOf":[{"type":"object","properties":{"candidatesFullyDeployed":{"type":"number","description":"Number of fully deployed candidates"},"candidatesInProgress":{"type":"number","description":"Number of candidates in progress"},"candidatesPending":{"type":"number","description":"Number of pending candidates"},"estimatedTimeToFullDeployment":{"type":"number","description":"Estimated time to deploy all candidates (minutes)"}},"required":["candidatesFullyDeployed","candidatesInProgress","candidatesPending"]}]},"baselineToLatestSummary":{"description":"Summary from baseline to latest","allOf":[{"type":"object","properties":{"totalCandidates":{"type":"number","description":"Total number of candidates"},"totalUniqueWorkItems":{"type":"number","description":"Total unique work items"},"totalUniqueCommits":{"type":"number","description":"Total unique commits"},"packageProgressions":{"description":"How packages evolved through candidates","type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Package name"},"journey":{"type":"array","description":"Version journey through candidates","items":{"type":"object","properties":{"version":{"type":"string"},"candidateIndex":{"type":"number","description":"-1 for baseline"}}}}},"required":["name","journey"]}}},"required":["totalCandidates","totalUniqueWorkItems","totalUniqueCommits","packageProgressions"]}]},"branchAnalysis":{"description":"Branch analysis if multiple branches involved","allOf":[{"type":"object","properties":{"mainBranch":{"type":"string","description":"Main branch name"},"featureBranches":{"type":"array","description":"Feature branch analysis","items":{"type":"object","properties":{"branch":{"type":"string"},"candidateCount":{"type":"number"},"firstCandidate":{"type":"string"},"lastCandidate":{"type":"string"}}}}},"required":["mainBranch","featureBranches"]}]}},"required":["deploymentPipeline","progressMetrics","baselineToLatestSummary"]}]},"analyzedAt":{"type":"string","description":"Analysis timestamp"}},"required":["repository","domain","baseline","orchestrationOrder","currentEnvironmentStates","candidates","candidatesByBranch","summary","analyzedAt"]}}}}},"tags":["release-candidates"]}}}}
```

## Get environment-specific progression analysis

> Analyzes progression for a specific environment including pending candidates

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates/rolling-analysis/{repository}/{domain}/environment/{environment}":{"get":{"operationId":"ReleaseCandidatesController_getEnvironmentProgression","summary":"Get environment-specific progression analysis","description":"Analyzes progression for a specific environment including pending candidates","parameters":[{"name":"repository","required":true,"in":"path","description":"Repository identifier (e.g., myorg/myrepo)","schema":{"type":"string"}},{"name":"domain","required":true,"in":"path","description":"Domain name","schema":{"type":"string"}},{"name":"environment","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}},{"name":"includeChangelog","required":false,"in":"query","description":"Include package changelogs","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Environment progression analysis"}},"tags":["release-candidates"]}}}}
```

## Assess deployment risk for next candidate

> Provides risk assessment for the next deployment to a specific environment

```json
{"openapi":"3.0.0","info":{"title":"sfp","version":"50.1.0-build.525"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/release-candidates/rolling-analysis/{repository}/{domain}/environment/{environment}/risk":{"get":{"operationId":"ReleaseCandidatesController_assessDeploymentRisk","summary":"Assess deployment risk for next candidate","description":"Provides risk assessment for the next deployment to a specific environment","parameters":[{"name":"repository","required":true,"in":"path","description":"Repository identifier (e.g., myorg/myrepo)","schema":{"type":"string"}},{"name":"domain","required":true,"in":"path","description":"Domain name","schema":{"type":"string"}},{"name":"environment","required":true,"in":"path","description":"Environment name","schema":{"type":"string"}}],"responses":{"200":{"description":"Deployment risk assessment"}},"tags":["release-candidates"]}}}}
```
