Skip to content

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 Deprecated: use DryRun in the request body. Plan the upload and return the same response without writing anything. Either one asks for a dry run.
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, as entries of its MutationSources, and Diff for the same change path by path with the values on both sides. They cost something to return, and on a dry run either one runs the merges a plan otherwise skips, so they are returned only when named. Context, with Diff, adds to each Diff the unchanged paths around the changes: every unchanged child of each map or array that holds a change, up to the resource, as ChangeType None. Supported values: Mutations, Diff, Context.

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

The body of an error response: the error as data (Error), and as one string (message) for clients written before Error.

Properties

Property Type Required Description
Error The error: its message, category (Type), HTTP status, details, and structured items.
message string The error as one string: its message, with any details, items, and individual errors appended. Kept for clients written before Error; new clients read Error.

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. The upload closes it afterwards, unless a ChangeWorkflow governs it.
ChangeWorkflowID string (uuid) The ChangeWorkflow governing the ChangeSet the upload opens, which a Space whose Component requires one needs. A ChangeSet a ChangeWorkflow governs is left open, with the Units the upload wrote in it, since closing it is gated on the workflow's Final prerequisites. Not accepted with ChangeSetID, whose ChangeSet names its own.
Clearance The guarded reasons the Unit writes are cleared for. A path whose guards this does not cover is not written, and the withheld change is reported in the Unit's Conflicts.
Components Array of UploadComponentRequest Placement of each component. Exactly one is supported.
DryRun boolean Plan the upload and return the same response without writing anything.
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.
Partial boolean The bundle is part of what its source owns: Units the source owns that it leaves out are left alone rather than emptied.
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 Component and labels. Default {{.Component.Slug}}-{{.Labels.Variant}}.
Subgroup string A category recorded on the Mutations of each Unit write. Alphanumeric, at most 64 characters, and not starting with ConfigHub.
TagID string (uuid) A Tag to put on the Revision each Unit the upload writes is left at, created Units included. Units the upload leaves Unchanged are not tagged. Requires Use permission on the Tag; a ChangeSet's or ChangeOrder's own Tag is refused. An upload with a Unit to write that the Tag already marks fails, and nothing is written.

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.