Source uploads

Stage an archive and publish it as the immutable source an app is created from.

Introduction

A source is the archive an app is built from: a zip of your code, or a Dockerfile with its build context. It is immutable and belongs to your organization, so the same source can back any number of apps and versions, each choosing its own entry point.

Creating an app names a source by sourceId, and so does updating the code an app runs. This flow is the only thing that produces one.

The flow

POST /v1/source-uploads
PUT  <transfer.url>
POST /v1/source-uploads/{uploadId}/complete

Zip and hash the archive before you start. Creating the session declares the archive's exact byte length and its lowercase SHA-256, and completion accepts only bytes that match what you declared.

The create response carries a transfer instruction beside the session: a method, a short-lived url for this upload's staging object, and the headers to send with it. That request is not one of the routes on this page. Send the archive to the URL you were given, with those headers, and then call complete.

Completion publishes the verified bytes and the ready session carries the sourceId to use. A session is pending until then, and ends as ready, rejected, expired or deleted. A rejected session keeps its rejectionReason and a retry returns the same result, so that reason is what to act on.

What the archive has to contain depends on its type. A code archive is your codebase, and the app points at its entry point with modelFile. A container archive carries a Dockerfile and a container.yaml at its root, plus whatever the Dockerfile copies in. See Writing a model and Bringing a container.

Create a source upload

POSTapi.serverless.runware.ai/v1/source-uploads

Creates an upload session for a source archive. The session belongs to the authenticated organization and names no app: an upload precedes any app, and the source it publishes may back several. The response contains a short-lived transfer instruction for one exact staging object. Repeating the request with the same idempotency key and declaration while the session is pending and unexpired returns the same upload resource with a refreshed transfer instruction. Replays with a different declaration, or after the session becomes ready, rejected, expired, or deleted, return 409.

The idempotencyKey is yours to choose and makes this call safe to retry: repeating it with the same declaration, while the session is still pending and has not expired, returns the same session with a fresh transfer instruction. Repeating it with a different declaration, or once the session has finished, answers 409.

Request

Body

declaredByteLength integerrequiredint64min: 1max: 10485760: Exact size of the archive in bytes, at most 10 MiB. Completion weighs the staged bytes against it and refuses an archive that does not match.

idempotencyKey stringrequiredmin: 1max: 255: Client-generated key used to make session creation safe to retry.

sha256 stringrequired: Lowercase SHA-256 digest of the complete archive.

sourceType stringrequired: Allowed values2 values

Response

upload objectrequired

Properties10 properties

id string (uuid)requiredUUID v4

sourceId string (uuid)nullableUUID v4: The immutable source this upload published. Set once the upload is ready. It is what app create and source update name. Equal to id, so a retry of completion returns the same value.

declaredByteLength integerrequiredint64min: 1

sha256 stringrequired

sourceType stringrequired: Possible values2 values

state stringrequired: Possible values5 values

rejectionReason stringnullable: Reason completion rejected the archive, when state is rejected.

expiresAt string (date-time)requireddate-time

createdAt string (date-time)requireddate-time

updatedAt string (date-time)requireddate-time

transfer variantrequired

Format 1: object5 properties

mode stringrequired: Possible values1 value

method stringrequired: Possible values1 value

url stringrequireduri: Short-lived URL for this upload's exact staging object.

headers objectrequired: Headers the client must include in the upload request.

expiresAt string (date-time)requireddate-time: Time after which the transfer instruction is no longer valid.

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`409`	The idempotency key was already used. `conflict` means the replay declared a different archive. The `source-upload-*` types mean the session the key names is no longer pending, and say which state it reached.
`413`	The request body exceeds its size limit: 10 MiB on `invoke-sync` and `invoke-async`, whose body carries the endpoint's payload, and 1 MiB on the other operations that answer with this response. `detail` names the limit in bytes.
`422`	The request was well-formed but semantically invalid (e.g. a missing or out-of-range field). A request that could not be parsed returns `400`. The `errors` array carries one entry per offending field.
`500`	Unexpected server error
`502`	An upstream service was unreachable or refused the request
`503`	A required service is temporarily unavailable

Complete a source upload

POSTapi.serverless.runware.ai/v1/source-uploads/{uploadId}/complete

Verifies the staging object's length, content type, and SHA-256 digest against the session declaration, applies the archive rules for the source type, and publishes the verified bytes as an immutable source artifact. The first success creates the source and returns the ready session carrying its sourceId. A retry returns the same session and the same sourceId. A rejected upload keeps its rejection so later retries return the same result.

Request

Path

uploadId string (uuid)requiredUUID v4: Source upload session identifier.

Response

id string (uuid)requiredUUID v4

sourceId string (uuid)nullableUUID v4: The immutable source this upload published. Set once the upload is ready. It is what app create and source update name. Equal to id, so a retry of completion returns the same value.

declaredByteLength integerrequiredint64min: 1

sha256 stringrequired

sourceType stringrequired: Possible values2 values

state stringrequired: Possible values5 values

rejectionReason stringnullable: Reason completion rejected the archive, when state is rejected.

expiresAt string (date-time)requireddate-time

createdAt string (date-time)requireddate-time

updatedAt string (date-time)requireddate-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`403`	Authenticated but not permitted to access this resource
`404`	Resource not found
`409`	The upload cannot be completed in its current state. The `type` says which state and what to do next: upload the object, retry, or open a new session.
`422`	The uploaded archive broke an artifact rule for its source type. The upload keeps this rejection: a later completion answers `409` with type `source-upload-rejected` and the stored reason. `errors[]` carries one entry per rule broken.
`500`	Unexpected server error
`502`	An upstream service was unreachable or refused the request
`503`	A required service is temporarily unavailable

Get a source upload

GETapi.serverless.runware.ai/v1/source-uploads/{uploadId}

Returns the upload session belonging to the authenticated organization. Once the upload is ready the session carries the sourceId it published. An upload belonging to another organization returns 404.

Request

Path

uploadId string (uuid)requiredUUID v4: Source upload session identifier.

Response

id string (uuid)requiredUUID v4

sourceId string (uuid)nullableUUID v4: The immutable source this upload published. Set once the upload is ready. It is what app create and source update name. Equal to id, so a retry of completion returns the same value.

declaredByteLength integerrequiredint64min: 1

sha256 stringrequired

sourceType stringrequired: Possible values2 values

state stringrequired: Possible values5 values

rejectionReason stringnullable: Reason completion rejected the archive, when state is rejected.

expiresAt string (date-time)requireddate-time

createdAt string (date-time)requireddate-time

updatedAt string (date-time)requireddate-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`404`	Resource not found
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

Abort a source upload

DELETEapi.serverless.runware.ai/v1/source-uploads/{uploadId}

Aborts an upload that has not published its source and removes its staging object. The session remains as a deleted tombstone so its staging key cannot be reused. Repeating a successful abort is idempotent. A ready upload cannot be aborted: the source it published is a resource in its own right, and the request answers 409 with type source-upload-completed.

Only a session that has not published its source can be aborted. Once it is ready the source exists in its own right and the request answers 409.

Request

Path

uploadId string (uuid)requiredUUID v4: Source upload session identifier.

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`404`	Resource not found
`409`	The upload is `ready`. The source it published is a resource in its own right, so the upload cannot be aborted.
`500`	Unexpected server error
`503`	A required service is temporarily unavailable

Get a source

GETapi.serverless.runware.ai/v1/sources/{sourceId}

Returns the immutable source artifact a completed upload published: its type and the length and digest upload completion verified. A source is organization-scoped and may be named by any number of apps and versions in that organization. One belonging to another organization returns 404. There is no list and no delete.

Request

Path

sourceId string (uuid)requiredUUID v4: Source artifact identifier.

Response

id string (uuid)requiredUUID v4

sourceType stringrequired: Possible values2 values

byteLength integerrequiredint64min: 1: Verified length of the archive in bytes.

sha256 stringrequired: Verified lowercase SHA-256 digest of the archive.

createdAt string (date-time)requireddate-time

Errors

Status	When
`400`	The request was malformed and could not be parsed (e.g. invalid JSON). A well-formed request that fails validation returns `422` instead.
`401`	Missing or invalid credentials
`404`	Resource not found
`500`	Unexpected server error
`503`	A required service is temporarily unavailable