> For the complete documentation index, see [llms.txt](https://docs.flxbl.io/flxbl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flxbl.io/flxbl/sfp-server/api-reference/release-candidates.md).

# Release Candidates

## Diff two release candidates (async, doc-store-backed)

> Returns the package-version delta and git file-level diff between two release candidates. Async, mirroring code-analysis / AI reports: a cached result is served immediately (\`status: available\`); otherwise the generate-release-diff flow is dispatched and \`status: pending\` is returned with a \`jobId\`. Poll this same endpoint (same \`from\`/\`to\`) until \`status\` becomes \`available\` — the result is keyed by (repository, from, to), not by \`jobId\`. Concurrent polls reuse the in-flight run.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.20.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ReleaseDiffResponse":{"type":"object","properties":{"status":{"type":"string","enum":["available","pending","error"],"description":"`available` — `data` holds the cached diff. `pending` — computation is running; poll the same query until `available`. `error` — computation failed."},"data":{"description":"The diff, present when status is `available`.","allOf":[{"$ref":"#/components/schemas/StoreReleaseDiffDto"}]},"jobId":{"type":"string","description":"Hatchet execution id of the in-flight computation (status `pending`)."},"message":{"type":"string","description":"Human-readable status detail."}},"required":["status"]},"StoreReleaseDiffDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"fromRelease":{"type":"string","description":"Baseline release ref (domain:releaseName)"},"toRelease":{"type":"string","description":"Target release ref (domain:releaseName)"},"packages":{"description":"Per-package version deltas","type":"array","items":{"$ref":"#/components/schemas/PackageDeltaDto"}},"summary":{"type":"object","description":"Counts by change type"},"fileDiff":{"type":"object","description":"Git file-level diff between the two release commits, grouped by package. Each package lists its changed files with status (A/M/D). Counts are exact; the file listing is capped (filesTruncated flags when the cap was hit). No patch hunks."},"computedAt":{"type":"string","description":"ISO timestamp the diff was computed"},"status":{"type":"string","description":"completed | failed"},"durationMs":{"type":"number"}},"required":["repositoryIdentifier","fromRelease","toRelease","packages","summary"]},"PackageDeltaDto":{"type":"object","properties":{"package":{"type":"string"},"fromVersion":{"type":"string"},"toVersion":{"type":"string"},"change":{"type":"string","enum":["added","removed","upgraded","downgraded","unchanged"]}},"required":["package","change"]}}},"paths":{"/sfp/api/release-candidates/diff":{"get":{"operationId":"ReleaseDiffController_getDiff","summary":"Diff two release candidates (async, doc-store-backed)","description":"Returns the package-version delta and git file-level diff between two release candidates. Async, mirroring code-analysis / AI reports: a cached result is served immediately (`status: available`); otherwise the generate-release-diff flow is dispatched and `status: pending` is returned with a `jobId`. Poll this same endpoint (same `from`/`to`) until `status` becomes `available` — the result is keyed by (repository, from, to), not by `jobId`. Concurrent polls reuse the in-flight run.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","description":"Repository identifier (owner/repo or org/project/repo).","schema":{"type":"string"}},{"name":"from","required":true,"in":"query","description":"Baseline release ref as `domain:releaseName`.","schema":{"type":"string"}},{"name":"to","required":true,"in":"query","description":"Target release ref as `domain:releaseName`.","schema":{"type":"string"}},{"name":"refresh","required":false,"in":"query","description":"Force a recompute, bypassing the cache (an in-flight run is still reused).","schema":{"type":"boolean"}}],"responses":{"200":{"description":"The diff (`available`) or the in-flight job (`pending`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReleaseDiffResponse"}}}},"400":{"description":"Missing required query parameter(s): repositoryIdentifier, from, to."},"401":{"description":"Unauthorized — invalid or missing token."},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["release-candidates"]}}}}
```

## Store a computed release diff (internal — called by the flow)

> Callback used by the generate-release-diff flow to persist its result into the doc store. Requires an application token.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.20.0"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"StoreReleaseDiffDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier"},"fromRelease":{"type":"string","description":"Baseline release ref (domain:releaseName)"},"toRelease":{"type":"string","description":"Target release ref (domain:releaseName)"},"packages":{"description":"Per-package version deltas","type":"array","items":{"$ref":"#/components/schemas/PackageDeltaDto"}},"summary":{"type":"object","description":"Counts by change type"},"fileDiff":{"type":"object","description":"Git file-level diff between the two release commits, grouped by package. Each package lists its changed files with status (A/M/D). Counts are exact; the file listing is capped (filesTruncated flags when the cap was hit). No patch hunks."},"computedAt":{"type":"string","description":"ISO timestamp the diff was computed"},"status":{"type":"string","description":"completed | failed"},"durationMs":{"type":"number"}},"required":["repositoryIdentifier","fromRelease","toRelease","packages","summary"]},"PackageDeltaDto":{"type":"object","properties":{"package":{"type":"string"},"fromVersion":{"type":"string"},"toVersion":{"type":"string"},"change":{"type":"string","enum":["added","removed","upgraded","downgraded","unchanged"]}},"required":["package","change"]}}},"paths":{"/sfp/api/release-candidates/diff/results":{"post":{"operationId":"ReleaseDiffController_storeResult","summary":"Store a computed release diff (internal — called by the flow)","description":"Callback used by the generate-release-diff flow to persist its result into the doc store. Requires an application token.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreReleaseDiffDto"}}}},"responses":{"201":{"description":"Diff stored."},"400":{"description":"Invalid request body."},"401":{"description":"Unauthorized — this endpoint requires an application token."},"403":{"description":"Forbidden - Requires role: application"}},"tags":["release-candidates"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/release-candidates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.