---
title: "Refresh a draft version's upload instructions"
method: POST
path: "/v1/spaces/{spaceId}/versions/{versionId}/uploads/refresh"
tags: ["Versions"]
---

# Refresh a draft version's upload instructions

`POST /v1/spaces/{spaceId}/versions/{versionId}/uploads/refresh`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/spaces/{spaceId}/versions/{versionId}/uploads/refresh`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Mints a fresh upload session for an unfinished version and lists only the files the runtime has not received yet, so an interrupted upload can continue where it stopped.

## Path parameters

- `spaceId` string, required
- `versionId` string, required

## Response `200`

Response for status 200

- object
  - `$schema` string, uri: Canonical JSON Schema URL for this response body. The server also sends it in the `Link: rel="describedby"` response header.
  - `data` object, required
    - `ignoredPaths` string[]: Deprecated; current servers return an empty array.
    - `versionId` string, required
    - `upload` object, nullable, required: Fresh runtime upload session; present only while files still need uploading. Upload first, then finalize.
      - `id` string, required: Upload session id (upl_…) minted by the runtime.
      - `mode` 'dist' | 'source', required: `dist` bytes are publishable output. `source` bytes must be transformed, unpacked, or built before publish.
      - `expiresAt` string, date-time, required: Instant when the session token expires. This rotates only the token, never the version lifecycle boundary. Resume always mints a fresh token.
      - `summary` object, required: Counts for the whole manifest, independent of target paging.
        - `upload` integer, required: Files that still need uploading.
        - `reused` integer, required: Files satisfied by hash reuse.
        - `ignored` integer: Deprecated; current servers return zero.
      - `targets` object[], required: Opaque upload targets, bounded by the instruction payload budget. Upload these, then call `links.refresh` for the remainder.
        - `path` string, required: Caller-local path/key identifying the bytes this target accepts.
        - `method` 'PUT' | 'POST', required: HTTP method to use for this target.
        - `url` union, required: Absolute or API-relative upload URL issued by the control plane.
          - string, uri
          - string
        - `headers` object, required: Exact headers to send with the upload request.
        - `body` object: Optional body recipe. Omitted means the client uploads the local bytes for `path`; `url` means POST the URL for server-side fetch.
          - `kind` 'url', required
          - `url` string, uri, required
        - `size` integer: Expected byte size when known.
        - `maxBytes` integer: Maximum accepted byte size when the server can advertise it.
        - `sha256` string
        - `contentType` string
      - `bulk` object: Optional direct runtime transport for this page's content-addressed targets. Clients that do not support it continue with targets.
        - `kind` 'zip-cas-v1', required
        - `method` 'PUT', required
        - `url` union, required: Upload-auth runtime URL that accepts a ZIP of SHA-named CAS blobs.
          - string, uri
          - string
        - `headers` object, required: Exact headers to send with the bulk upload request.
        - `maxCompressedBytes` integer, required
        - `maxExpandedBytes` integer, required
        - `maxBlobs` integer, required
      - `links` object, required
        - `refresh` string, required
        - `resume` string
        - `finalize` string, required
      - `details` object
        - `reused` object[]
          - `path` string, required
          - `reason` string, required
        - `diagnostics` object[]
          - `code` string, required: Stable snake_case diagnostic code naming the public contract that produced it.
          - `severity` 'info' | 'warning' | 'error', required: How actionable the diagnostic is.
          - `message` string, required: Human-readable explanation with enough detail to act on.
          - `path` string, nullable: Artifact path the diagnostic points at, for example "_headers:12", when one exists.
          - `provider` 'infra' | 'dns' | 'registrar' | 'runtime', nullable: Upstream system the diagnostic originated from, when not Spacefast itself.
          - `details` object, nullable: Machine-readable context for the diagnostic code.
          - `fix` string, nullable: Concrete, agent-actionable remediation hint, when one can be derived.
          - `retryable` boolean, nullable: Whether retrying the same operation can resolve this diagnostic without the caller changing anything.

## Other responses

- `default`: Problem details (RFC 9457). Any 4xx/5xx response is one `application/problem+json` document.

---

[API](https://skmtc.dev/spacefast/apis/spacefast-api.md) · [All operations](https://skmtc.dev/spacefast/apis/spacefast-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spacefast/apis/spacefast-api/revisions/bd165bc7c983?raw)