Upload
Operations
| Method | Endpoint | Description |
|---|---|---|
POST |
/upload |
Upload a bundle of configuration |
Upload a bundle of configuration
POST /upload
Takes a bundle of rendered configuration files, or pulls one from an OCI registry, splits it into resources, and makes a Space's Units, Links, and Invocations match it. Creates what is missing, 3-way merges what changed, and empties the Units of resources the bundle no longer contains, so uploading the same bundle again changes nothing. Every resource becomes its own Unit.
Operation ID: Upload
Parameters
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
dry_run |
boolean | Plan the upload and return the same response without writing anything. | |
include |
string | Comma-separated parts of the result to return in addition to the actions: Mutations for what each Unit write changed, or on a dry run would change. It costs something to return, and on a dry run it runs the merges a plan otherwise skips, so it is returned only when named. |
Request Body
Content-Type: application/json
Schema: UploadRequest
Responses
| Status | Description | Content-Type | Schema |
|---|---|---|---|
| 200 | OK | application/json |
UploadResult |
| 207 | Multi-Status: some Unit or Link writes failed, each carrying its own error | application/json |
UploadResult |
| 400 | Upload request is invalid (Bad Request). | application/json |
StandardErrorResponse |
| 401 | Unauthorized access. | application/json |
StandardErrorResponse |
| 403 | Forbidden access. | application/json |
StandardErrorResponse |
| 404 | Upload not found. | application/json |
StandardErrorResponse |
| 409 | Upload data conflict. Data has changed since last read. | application/json |
StandardErrorResponse |
| 422 | The bundle could not be pulled from Source.Ref | application/json |
StandardErrorResponse |
| 500 | Something went wrong while processing Upload. | application/json |
StandardErrorResponse |
| 504 | Pulling the bundle from Source.Ref took too long | application/json |
StandardErrorResponse |
| default | Unexpected error. | application/json |
StandardErrorResponse |
Schemas
StandardErrorResponse
Error response details.
Properties
| Property | Type | Required | Description |
|---|---|---|---|
Code |
string | HTTP status code of the response. | |
Message |
string | Message returned with the response. |
UploadRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
ChangeDescription |
string | Recorded on each Unit write. | |
ChangeSetDescription |
string | ||
ChangeSetID |
string (uuid) | An existing ChangeSet to record the writes in. Default: one new ChangeSet per Space. | |
Components |
Array of UploadComponentRequest |
Placement of each component. Exactly one is supported. | |
Files |
Array of UploadRequestFile |
The bundle's files. Paths must be relative and may not contain "..". Exactly one of Files and Source.Pull is given. | |
Source |
UploadSourceInfo |
||
SpaceLabels |
object | Labels applied to every Space, merge-patch: keys given are set, keys omitted are left alone. | |
SpacePattern |
string | Slug pattern for created Spaces, over the Space's labels. Default {{.Labels.Component}}-{{.Labels.Variant}}. |
UploadResult
Properties
| Property | Type | Required | Description |
|---|---|---|---|
Components |
Array of UploadComponentResult |
||
DryRun |
boolean | True when nothing was written. | |
Plan |
string | Digest of the planned actions. | |
SourceDigest |
string | The digest of the manifest the server pulled, when Source.Pull was set. Send it as Source.Digest to upload exactly the bundle a dry run read. |