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

# Changesets

## GET /sfp/api/changesets

> List project-scoped changesets

```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/changesets":{"get":{"operationId":"ChangesetsController_listChangesets","summary":"List project-scoped changesets","parameters":[{"name":"projectIdentifier","required":true,"in":"query","description":"Project identifier","schema":{"type":"string"}},{"name":"sourceOrgUsername","required":false,"in":"query","description":"Filter by source org username","schema":{"type":"string"}}],"responses":{"200":{"description":"Changesets returned"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Changesets"]}}}}
```

## POST /sfp/api/changesets

> Create and materialize a changeset from selected org components

```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":{"CreateChangesetDto":{"type":"object","properties":{"projectIdentifier":{"type":"string","description":"Project identifier for the current Codev project"},"repositoryIdentifier":{"type":"string","description":"Repository identifier. Defaults to projectIdentifier when omitted."},"name":{"type":"string","description":"User-defined changeset display name"},"sourceOrgUsername":{"type":"string","description":"Source org username selected in Org Explorer"},"sourceEnvironmentName":{"type":"string","description":"Source environment name when the source org is a managed environment"},"templateId":{"type":"string","description":"Changeset template identifier used to govern this changeset"},"selectedComponents":{"description":"Selected org explorer components","type":"array","items":{"$ref":"#/components/schemas/ChangesetComponentDto"}}},"required":["projectIdentifier","name","sourceOrgUsername","selectedComponents"]},"ChangesetComponentDto":{"type":"object","properties":{"metadataType":{"type":"string","description":"Salesforce metadata type, for example ApexClass or CustomObject"},"memberName":{"type":"string","description":"Salesforce metadata member name"},"operation":{"type":"string","enum":["deploy","delete"],"description":"How this component participates in the changeset"},"destructiveStage":{"type":"string","enum":["pre","post"],"description":"Destructive stage when operation is delete"}},"required":["metadataType","memberName"]}}},"paths":{"/sfp/api/changesets":{"post":{"operationId":"ChangesetsController_createChangeset","summary":"Create and materialize a changeset from selected org components","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChangesetDto"}}}},"responses":{"201":{"description":"Changeset created and materialization dispatched"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Changesets"]}}}}
```

## GET /sfp/api/changesets/{changesetId}

> Get a changeset and its deployment history

```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/changesets/{changesetId}":{"get":{"operationId":"ChangesetsController_getChangeset","summary":"Get a changeset and its deployment history","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"projectIdentifier","required":true,"in":"query","description":"Project identifier","schema":{"type":"string"}}],"responses":{"200":{"description":"Changeset returned"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Changesets"]}}}}
```

## GET /sfp/api/changesets/{changesetId}/materialized-source

> Get materialized source files for a changeset component

```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/changesets/{changesetId}/materialized-source":{"get":{"operationId":"ChangesetsController_getMaterializedComponentSource","summary":"Get materialized source files for a changeset component","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"projectIdentifier","required":true,"in":"query","description":"Project identifier","schema":{"type":"string"}},{"name":"metadataType","required":true,"in":"query","description":"Salesforce metadata type to read from the materialized source snapshot","schema":{"type":"string"}},{"name":"memberName","required":true,"in":"query","description":"Salesforce metadata member name to read from the materialized source snapshot","schema":{"type":"string"}}],"responses":{"200":{"description":"Materialized component source returned"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Changesets"]}}}}
```

## GET /sfp/api/changesets/{changesetId}/deployments

> List deployments for a changeset

```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/changesets/{changesetId}/deployments":{"get":{"operationId":"ChangesetsController_listDeployments","summary":"List deployments for a changeset","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"projectIdentifier","required":true,"in":"query","description":"Project identifier","schema":{"type":"string"}}],"responses":{"200":{"description":"Deployment records returned"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Changesets"]}}}}
```

## POST /sfp/api/changesets/{changesetId}/retry

> Retry materialization for a failed changeset

```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":{"ChangesetProjectQueryDto":{"type":"object","properties":{"projectIdentifier":{"type":"string","description":"Project identifier"}},"required":["projectIdentifier"]}}},"paths":{"/sfp/api/changesets/{changesetId}/retry":{"post":{"operationId":"ChangesetsController_retryChangeset","summary":"Retry materialization for a failed changeset","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetProjectQueryDto"}}}},"responses":{"200":{"description":"Materialization retry dispatched"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Changesets"]}}}}
```

## POST /sfp/api/changesets/{changesetId}/install

> Install or validate a changeset artifact in a target org

```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":{"InstallChangesetDto":{"type":"object","properties":{"projectIdentifier":{"type":"string","description":"Project identifier"},"repositoryIdentifier":{"type":"string","description":"Repository identifier. Defaults to projectIdentifier when omitted."},"targetOrg":{"type":"string","description":"Target org username or alias"},"targetEnvironmentName":{"type":"string","description":"Target environment name when known"},"checkOnly":{"type":"boolean","description":"Validate deployment without committing changes","default":false}},"required":["projectIdentifier","targetOrg"]}}},"paths":{"/sfp/api/changesets/{changesetId}/install":{"post":{"operationId":"ChangesetsController_installChangeset","summary":"Install or validate a changeset artifact in a target org","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InstallChangesetDto"}}}},"responses":{"201":{"description":"Install changeset workflow dispatched"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Changesets"]}}}}
```

## POST /sfp/api/changesets/{changesetId}/pull-requests

> Create a pull request from the materialized changeset source

```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":{"CreateChangesetPullRequestDto":{"type":"object","properties":{"projectIdentifier":{"type":"string","description":"Project identifier"},"repositoryIdentifier":{"type":"string","description":"Deprecated compatibility field. When provided, it must match the changeset repository."},"targetBranch":{"type":"string","description":"Tracked target branch for the pull request"},"title":{"type":"string","description":"Pull request title. Defaults to a changeset-generated title."},"description":{"type":"string","description":"Pull request body markdown. Defaults to a changeset-generated body."},"draft":{"type":"boolean","description":"Create as draft pull request","default":false}},"required":["projectIdentifier","targetBranch"]}}},"paths":{"/sfp/api/changesets/{changesetId}/pull-requests":{"post":{"operationId":"ChangesetsController_createPullRequest","summary":"Create a pull request from the materialized changeset source","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateChangesetPullRequestDto"}}}},"responses":{"201":{"description":"Changeset pull request workflow dispatched"},"403":{"description":"Forbidden - Requires role: member, owner, application"}},"tags":["Changesets"]}}}}
```

## POST /sfp/api/changesets/internal/{changesetId}/materialization

> Internal worker callback for changeset materialization status

```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":{"ChangesetMaterializationUpdateDto":{"type":"object","properties":{"projectIdentifier":{"type":"string","description":"Project identifier"},"status":{"type":"object","description":"Materialization status"},"taskExecutionId":{"type":"string"},"artifactName":{"type":"string"},"artifactVersion":{"type":"string"},"artifactCoordinates":{"type":"string"},"error":{"type":"string"},"materializedSource":{"description":"Object-storage-backed immutable source snapshot captured during materialization","allOf":[{"$ref":"#/components/schemas/ChangesetMaterializedSourceSnapshotDto"}]}},"required":["projectIdentifier","status"]},"ChangesetMaterializedSourceSnapshotDto":{"type":"object","properties":{"version":{"type":"number","enum":[1]},"objectPrefix":{"type":"string","description":"Object storage prefix containing materialized source files"},"manifestObjectKey":{"type":"string","description":"Object storage key containing the materialized source manifest"},"capturedAt":{"type":"string","description":"Snapshot capture timestamp"},"fileCount":{"type":"number","description":"Number of unique source objects uploaded"},"sizeBytes":{"type":"number","description":"Total uploaded source bytes"},"components":{"type":"array","items":{"$ref":"#/components/schemas/ChangesetMaterializedComponentDto"}}},"required":["version","objectPrefix","manifestObjectKey","capturedAt","fileCount","sizeBytes","components"]},"ChangesetMaterializedComponentDto":{"type":"object","properties":{"metadataType":{"type":"string","description":"Salesforce metadata type, for example ApexClass or CustomObject"},"memberName":{"type":"string","description":"Salesforce metadata member name"},"operation":{"type":"string","enum":["deploy","delete"],"description":"How this component participates in the changeset"},"destructiveStage":{"type":"string","enum":["pre","post"],"description":"Destructive stage when operation is delete"},"sourceData":{"description":"Materialized source files","type":"array","items":{"$ref":"#/components/schemas/ChangesetMaterializedFileDto"}}},"required":["metadataType","memberName","sourceData"]},"ChangesetMaterializedFileDto":{"type":"object","properties":{"fileName":{"type":"string","description":"Retrieved source file name"},"relativePath":{"type":"string","description":"Retrieved source file path relative to the materialized project"},"objectKey":{"type":"string","description":"Object storage key containing this materialized source file"},"fullName":{"type":"string","description":"Salesforce full name for the retrieved file"},"type":{"type":"string","description":"Salesforce metadata type for the retrieved file"},"state":{"type":"string","description":"Retrieve response state for the source file"},"contentType":{"type":"string","description":"Stored source file content type"},"sizeBytes":{"type":"number","description":"Stored source file size in bytes"},"sha256":{"type":"string","description":"Stored source file SHA-256 digest"},"fetchedAt":{"type":"string","description":"Timestamp when this source file was fetched"}},"required":["fileName","relativePath","objectKey","fullName","type","state","contentType","sizeBytes","sha256","fetchedAt"]}}},"paths":{"/sfp/api/changesets/internal/{changesetId}/materialization":{"post":{"operationId":"ChangesetsController_updateMaterialization","summary":"Internal worker callback for changeset materialization status","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetMaterializationUpdateDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: application"}},"tags":["Changesets"]}}}}
```

## POST /sfp/api/changesets/internal/{changesetId}/deployments/{deploymentId}

> Internal worker callback for changeset deployment status

```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":{"ChangesetDeploymentUpdateDto":{"type":"object","properties":{"projectIdentifier":{"type":"string","description":"Project identifier"},"status":{"type":"object","description":"Deployment status"},"taskExecutionId":{"type":"string"},"error":{"type":"string"}},"required":["projectIdentifier","status"]}}},"paths":{"/sfp/api/changesets/internal/{changesetId}/deployments/{deploymentId}":{"post":{"operationId":"ChangesetsController_updateDeployment","summary":"Internal worker callback for changeset deployment status","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"deploymentId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetDeploymentUpdateDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: application"}},"tags":["Changesets"]}}}}
```

## POST /sfp/api/changesets/internal/{changesetId}/pull-requests/{pullRequestId}

> Internal worker callback for changeset pull request status

```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":{"ChangesetPullRequestUpdateDto":{"type":"object","properties":{"projectIdentifier":{"type":"string","description":"Project identifier"},"status":{"type":"object","description":"Pull request creation status"},"taskExecutionId":{"type":"string"},"sourceBranch":{"type":"string"},"prUrl":{"type":"string"},"prNumber":{"type":"number"},"error":{"type":"string"}},"required":["projectIdentifier","status"]}}},"paths":{"/sfp/api/changesets/internal/{changesetId}/pull-requests/{pullRequestId}":{"post":{"operationId":"ChangesetsController_updatePullRequest","summary":"Internal worker callback for changeset pull request status","parameters":[{"name":"changesetId","required":true,"in":"path","schema":{"type":"string"}},{"name":"pullRequestId","required":true,"in":"path","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangesetPullRequestUpdateDto"}}}},"responses":{"403":{"description":"Forbidden - Requires role: application"}},"tags":["Changesets"]}}}}
```


---

# 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/changesets.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.