> 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/gc-ledger.md).

# GC Ledger

## Ingest gc-ledger events from a build

> Records component drop observations (detected, moved) from a build's source scan. Each event upserts the ledger entry for the component on the branch.\
> \
> Resolution states are never client-asserted: restored/handled transitions are derived server-side from published package manifests, and dismissals go through the dismiss endpoint with user identity.\
> \
> Repeat detections of an unchanged state refresh the entry's lastEventAt without growing its event history. Dismissed entries are not re-opened by repeat detections.\
> \
> Ingestion also triggers reconciliation of the branch's open entries against the latest published package manifests — builds with no drops still post (with an empty events array) so previously dropped components that were restored, moved, or covered by destructive changes get resolved.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"IngestGcEventsDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., flxbl-io/sf-core)"},"branch":{"type":"string","description":"Branch the events were detected on"},"commitSha":{"type":"string","description":"Commit SHA of the build that produced the events"},"buildNumber":{"type":"number","description":"Build number that produced the events"},"events":{"description":"Ledger events to ingest","type":"array","items":{"$ref":"#/components/schemas/GcEventDto"}}},"required":["repositoryIdentifier","branch","events"]},"GcEventDto":{"type":"object","properties":{"type":{"type":"string","description":"Event type","enum":["detected","moved"]},"packageName":{"type":"string","description":"Package the component was dropped from"},"componentType":{"type":"string","description":"Metadata type of the component"},"fullName":{"type":"string","description":"Full name of the component"},"packageType":{"type":"string","description":"Package type (source, unlocked, diff)"},"packageVersion":{"type":"string","description":"Package version that triggered the event"},"baselineVersion":{"type":"string","description":"Baseline package version the drop was detected against"},"orgImpact":{"type":"string","description":"What the drop means for orgs that already have the component: unlocked upgrades attempt to delete some types (auto-deletable — can be blocked by org dependencies), deprecate the rest; source packages orphan everything","enum":["auto-deletable","deprecated","orphaned"]},"movedTo":{"type":"string","description":"Package the component moved to (moved events only)"}},"required":["type","packageName","componentType","fullName"]}}},"paths":{"/sfp/api/gc-ledger/events":{"post":{"operationId":"GcLedgerController_ingestEvents","summary":"Ingest gc-ledger events from a build","description":"Records component drop observations (detected, moved) from a build's source scan. Each event upserts the ledger entry for the component on the branch.\n\nResolution states are never client-asserted: restored/handled transitions are derived server-side from published package manifests, and dismissals go through the dismiss endpoint with user identity.\n\nRepeat detections of an unchanged state refresh the entry's lastEventAt without growing its event history. Dismissed entries are not re-opened by repeat detections.\n\nIngestion also triggers reconciliation of the branch's open entries against the latest published package manifests — builds with no drops still post (with an empty events array) so previously dropped components that were restored, moved, or covered by destructive changes get resolved.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IngestGcEventsDto"}}}},"responses":{"201":{"description":"Events ingested and branch reconciled"},"400":{"description":"Invalid request body"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: application"}},"tags":["GC Ledger"]}}}}
```

## Query gc-ledger entries

> Lists components dropped from packages across a repository, optionally scoped to a branch. Filter by status to see what is pending garbage collection (status=detected) or what has been resolved.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}}},"paths":{"/sfp/api/gc-ledger":{"get":{"operationId":"GcLedgerController_getEntries","summary":"Query gc-ledger entries","description":"Lists components dropped from packages across a repository, optionally scoped to a branch. Filter by status to see what is pending garbage collection (status=detected) or what has been resolved.","parameters":[{"name":"repositoryIdentifier","required":true,"in":"query","schema":{"type":"string"}},{"name":"branch","required":false,"in":"query","description":"Branch to scope to; omit for all branches","schema":{"type":"string"}},{"name":"status","required":false,"in":"query","schema":{"enum":["detected","moved","handled","restored","dismissed","owned-elsewhere","reclaimed"],"type":"string"}},{"name":"package","required":false,"in":"query","description":"Filter by package name","schema":{"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Max entries (default 100, max 500)","schema":{"type":"number"}}],"responses":{"200":{"description":"Ledger entries, newest first"},"400":{"description":"Missing repositoryIdentifier or invalid status"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["GC Ledger"]}}}}
```

## Dismiss a gc-ledger entry

> Manually acknowledges a dropped component so it no longer shows as pending garbage collection. Dismissal is sticky against repeat detections; the entry only re-opens if the component is restored and dropped again.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"DismissGcEntryDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., flxbl-io/sf-core)"},"branch":{"type":"string","description":"Branch the ledger entry belongs to"},"packageName":{"type":"string","description":"Package the component was dropped from"},"componentType":{"type":"string","description":"Metadata type of the component"},"fullName":{"type":"string","description":"Full name of the component"},"reason":{"type":"string","description":"Reason for dismissing the entry"}},"required":["repositoryIdentifier","branch","packageName","componentType","fullName"]}}},"paths":{"/sfp/api/gc-ledger/dismiss":{"patch":{"operationId":"GcLedgerController_dismissEntry","summary":"Dismiss a gc-ledger entry","description":"Manually acknowledges a dropped component so it no longer shows as pending garbage collection. Dismissal is sticky against repeat detections; the entry only re-opens if the component is restored and dropped again.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DismissGcEntryDto"}}}},"responses":{"200":{"description":"Entry dismissed"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, owner, application"},"404":{"description":"No ledger entry for the component"}},"tags":["GC Ledger"]}}}}
```

## Apply org verification results for an environment

> Records the verified presence of dropped components in one registered environment's org. When an entry is positively confirmed absent in ALL registered environments tracking the branch, it is removed from the ledger. unknown results never count as absent, and nothing is removed while zero environments are registered.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"OrgCheckResultsDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., flxbl-io/sf-core)"},"branch":{"type":"string","description":"Branch the checked entries belong to"},"environment":{"type":"string","description":"Registered environment name the org was checked for"},"results":{"description":"Per-component verification results","type":"array","items":{"$ref":"#/components/schemas/OrgCheckResultDto"}}},"required":["repositoryIdentifier","branch","environment","results"]},"OrgCheckResultDto":{"type":"object","properties":{"packageName":{"type":"string","description":"Package the component was dropped from"},"componentType":{"type":"string","description":"Metadata type of the component"},"fullName":{"type":"string","description":"Full name of the component"},"presence":{"type":"string","description":"Verified presence in the environment org. unknown never counts as absent.","enum":["present","absent","unknown"]}},"required":["packageName","componentType","fullName","presence"]}}},"paths":{"/sfp/api/gc-ledger/org-check":{"post":{"operationId":"GcLedgerController_applyOrgCheck","summary":"Apply org verification results for an environment","description":"Records the verified presence of dropped components in one registered environment's org. When an entry is positively confirmed absent in ALL registered environments tracking the branch, it is removed from the ledger. unknown results never count as absent, and nothing is removed while zero environments are registered.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrgCheckResultsDto"}}}},"responses":{"201":{"description":"Results applied; confirmed-absent entries removed"},"400":{"description":"Invalid request body"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["GC Ledger"]}}}}
```

## Undo a dismissal

> Returns a dismissed entry to detected (pending cleanup). Only dismissed entries can be reopened; the action is recorded with the acting user.

```json
{"openapi":"3.0.0","info":{"title":"sfp server","version":"51.40.2"},"security":[{"access-token":[]}],"components":{"securitySchemes":{"access-token":{"scheme":"bearer","bearerFormat":"JWT","type":"http","in":"header"}},"schemas":{"ReopenGcEntryDto":{"type":"object","properties":{"repositoryIdentifier":{"type":"string","description":"Repository identifier (e.g., flxbl-io/sf-core)"},"branch":{"type":"string","description":"Branch the ledger entry belongs to"},"packageName":{"type":"string","description":"Package the component was dropped from"},"componentType":{"type":"string","description":"Metadata type of the component"},"fullName":{"type":"string","description":"Full name of the component"},"reason":{"type":"string","description":"Reason for undoing the dismissal"}},"required":["repositoryIdentifier","branch","packageName","componentType","fullName"]}}},"paths":{"/sfp/api/gc-ledger/reopen":{"patch":{"operationId":"GcLedgerController_reopenEntry","summary":"Undo a dismissal","description":"Returns a dismissed entry to detected (pending cleanup). Only dismissed entries can be reopened; the action is recorded with the acting user.","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReopenGcEntryDto"}}}},"responses":{"200":{"description":"Entry reopened"},"400":{"description":"Entry is not dismissed"},"401":{"description":"Unauthorized"},"403":{"description":"Forbidden - Requires role: member, owner, application"},"404":{"description":"No ledger entry for the component"}},"tags":["GC Ledger"]}}}}
```


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.flxbl.io/flxbl/sfp-server/api-reference/gc-ledger.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.