Skip to content
Docs
Console

Page and section titles. Use your browser's find for words inside a page.

Uploads

Put a checkpoint into your organization's store and deploy it as its own source. Write the files yourself through signed URLs, or have Boardwalk copy them from your bucket.

POST /v1/uploads

Authorization

Authorizationheader · string
Bearer $BOARDWALK_API_KEY. Requires deployments:write.
Content-Typeheader · stringrequired
application/json

Request

Request · cURL
curl https://api.boardwalk.cloud/v1/uploads \
  -H "Authorization: Bearer $BOARDWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "licence": "apache-2.0",
    "files": [
      {"path": "config.json", "size": 726, "sha256": "660db3b7…"},
      {"path": "tokenizer.json", "size": 11422654, "sha256": "aeb13307…"},
      {"path": "model.safetensors", "size": 1503300328, "sha256": "f47f7117…"}
    ]
  }'

Request body

filesobject[]
Every serving file of the checkpoint: config.json, the tokenizer files, the root *.safetensors shards and their index. Nothing else is stored. 1 to 2,048 files.
Child fields
pathstring
Path relative to the checkpoint root.
sizeinteger
Exact size in bytes.
sha256string
Lowercase hex digest of the file.
licencestringoptional
Licence label, read by the licence check as a model card's license, for example apache-2.0.
pullobjectoptional
Instead of files: copy the checkpoint from a connected bucket. See Pull from your bucket.

Response

Example response. IDs, token counts, and rates are illustrative.

200 · application/json
{
  "id": "upl_example",
  "object": "upload",
  "status": "uploading",
  "files": [
    {
      "path": "config.json",
      "size": 726,
      "sha256": "660db3b7…",
      "upload": "single",
      "part_bytes": 726,
      "parts": 1
    },
    {
      "path": "model.safetensors",
      "size": 1503300328,
      "sha256": "f47f7117…",
      "upload": "multipart",
      "part_bytes": 16777216,
      "parts": 90
    }
  ],
  "total_bytes": 1514723708,
  "licence": "apache-2.0",
  "failure": null,
  "expires_at": "2026-11-03T01:50:01.771Z",
  "created_at": "2026-10-31T01:50:01.771Z",
  "updated_at": "2026-10-31T01:50:01.771Z"
}
idstring
Upload ID.
object"upload"
Object type.
statusstring
uploading until sealed, importing while a pull copies, verifying while every file is read back against its hash, then ready or failed.
filesobject[]
The manifest, with how each file is written.
Child fields
uploadstring
single for one PUT (under 64 MiB), or multipart.
part_bytesinteger
Bytes in every part but the last.
partsinteger
Number of parts.
total_bytesinteger
Sum of the files' sizes.
failurestring | null
Why a failed upload failed, naming the file.
expires_atstring | null
When an unsealed upload is deleted, 72 hours after creation. Null once sealed.

Creating an upload answers 201. If your organization already stored the same bytes, it answers 200 with that upload instead. A ready upload counts toward your stored weights, deployed or not, until you delete it; deleting a model it backs keeps it. Past the included storage allowance, uploads need a credit balance, since stored bytes bill on the storage line.

Write the files

POST /v1/uploads/{id}/urls answers signed writes for one file. A single file gets one PUT whose headers carry its sha256, which the store checks. A multipart file gets up to 1,000 part URLs from part from. URLs expire after an hour; ask again for more. Send each part as a plain PUT of exactly part_bytes bytes, the last part shorter, with the headers each URL lists.

pathstringrequired
A path from the manifest.
fromintegeroptional
First part number. Default: 1.
countintegeroptional
Parts to sign, 1 to 1,000. Default: 1,000.
Request · cURL
curl https://api.boardwalk.cloud/v1/uploads/upl_example/urls \
  -H "Authorization: Bearer $BOARDWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"path": "model.safetensors", "from": 1, "count": 1000}'
200 · application/json
{
  "path": "model.safetensors",
  "upload": "multipart",
  "part_bytes": 16777216,
  "parts": [
    { "number": 1, "url": "https://…", "headers": {} },
    { "number": 2, "url": "https://…", "headers": {} }
  ],
  "expires_at": "2026-10-31T02:50:01.000Z"
}

Seal and verify

POST /v1/uploads/{id}/seal completes every file’s parts and starts verification. It answers 202 with status verifying, and a file with parts missing answers 409. Boardwalk then reads every file back against its declared sha256. Poll GET /v1/uploads/{id} with deployments:read until the status is ready, or failed with failure naming the file whose bytes did not match. A sealed upload never changes.

Deploy an upload

Preview and deploy name the upload as the source. Send model_name, since an upload names no model. Only your organization can preview or deploy its uploads. See Create a deployment for the other fields.

Deploy an upload
curl https://api.boardwalk.cloud/v1/deployments \
  -H "Authorization: Bearer $BOARDWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: support-upload-1" \
  -d '{"model_name":"support","source":{"kind":"artifact","id":"upl_example"},"serving":{"card":"HOST_H100_80"},"serve":false}'

Delete an upload

DELETE /v1/uploads/{id} aborts an unsealed upload, or deletes a stored one that no revision serves. Delete the model first otherwise. A failed upload can be deleted once its copy settles, within 15 minutes of the failure; until then the delete answers 409.

Pull from your bucket

For a checkpoint already in object storage, Boardwalk copies it cloud to cloud, without the bytes passing through your machine. Connect the bucket once with POST /v1/source-connections, then create an upload with a pull instead of files.

  • AWS S3: send kind: s3, a name, the bucket’s region and a role_arn. The answer’s trust names the principal your role must trust and the external_id its trust policy must require. The role needs s3:ListBucket on the bucket and s3:GetObject on the prefix. No secret changes hands.
  • S3-compatible stores such as R2, MinIO, Tigris or GCS interoperability: send kind: s3_compatible, a name, a region (or auto), an https endpoint, access_key_id and secret_access_key. The keys are stored encrypted under your organization and never returned.
Connect a bucket and pull
curl https://api.boardwalk.cloud/v1/source-connections \
  -H "Authorization: Bearer $BOARDWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"s3","name":"models","region":"us-east-1","role_arn":"arn:aws:iam::123456789012:role/boardwalk-reader"}'

curl https://api.boardwalk.cloud/v1/uploads \
  -H "Authorization: Bearer $BOARDWALK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pull":{"connection_id":"conn_example","bucket":"acme-models","prefix":"support/"},"licence":"apache-2.0"}'

The prefix is listed at once and the upload answers with status importing. The copy hashes every file as it arrives, and the upload becomes ready or failed with why. An object that changes during the copy fails it. List connections with GET /v1/source-connections. Revoke one with DELETE /v1/source-connections/{id}: its keys are dropped, a pull in flight fails at its next read, and stored checkpoints are unaffected.

Errors

Errors use the shared error format. Save the x-request-id response header for receipts and support.