Publishing

Publish files or capture a website and get a live URL

Publish files, a zip/tar archive, or a public HTTPS website and get a Spacefast URL. Pass sourceUrl to capture and publish a website; URL publishing must be enabled for the caller and is mutually exclusive with files, deletions, and archive uploads. URL publishes and archives that need a build return a durable Build receipt with next.action=poll; follow links.status until publication completes. The Build's capture field reports URL capture progress and quality evidence; an unmeasured visual comparison is not a passing comparison. Use a stable Idempotency-Key when retrying the same request. Already-built files and static website archives publish directly and wait for finalization by default; pass async=1 to return an operation link to poll instead. For buildable source on a Spacefast-managed Space, the receipt's git block provides the repository remote and the Build's input.commit identifies the source commit; later git pushes continue that repository history. The Open link provides reusable access; anonymous Spaces also receive a Claim link for ownership transfer. New Spaces are Private by default. Pass spaceId to update an existing Space; otherwise a new Space is created.

post/v1/publish

Request

  • Base URL: https://api.spacefast.com
  • URL: https://api.spacefast.com/v1/publish
  • Auth: one of:
    • none
    • HTTP bearer
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.spacefast.com/v1/auth/oauth2/authorize, token URL https://api.spacefast.com/v1/auth/oauth2/token; client credentials, token URL https://api.spacefast.com/v1/auth/oauth2/token, scopes: spaces:publish)
    • OAuth 2 (authorization code, authorization URL https://api.spacefast.com/v1/auth/oauth2/authorize, token URL https://api.spacefast.com/v1/auth/oauth2/token; client credentials, token URL https://api.spacefast.com/v1/auth/oauth2/token, scopes: publish:write)

Query parameters

async'1' | 'true' | '0' | 'false'

Controls the finalize transport. Omit the parameter, or pass 0 or false, to wait for the finalize and return the terminal receipt, degrading to a poll receipt only at the in-request ceiling. Pass 1 or true to return immediately with the operation to poll. Project archives always return a durable Build receipt and poll URL instead of holding the request open.

Headers

Idempotency-Keystring

Optional client-generated key, at most 255 characters, that makes this write safe to retry. The first request with a given key stores its outcome, scoped to your tenant, credential, and route. A retry with the same key and an identical body does not execute again: the server replays the stored response and marks it Idempotency-Replayed: true. A credential-free publish request that sends this header must also send X-Spacefast-Idempotency-Principal. A request that reuses a key with a different body fails with 409 idempotency_key_reused. A duplicate request that arrives while the first is still in flight fails with 409 idempotency_conflict_in_progress. The server keeps each key for 24 hours.

X-Spacefast-Idempotency-Principalstring

Required with Idempotency-Key on a credential-free publish. Send a stable 64-character hexadecimal value that only the caller knows, and send it unchanged on every retry. It isolates the stored one-time claim and upload credentials from other anonymous callers. Never log or share this value.

Request body

spaceIdstring
teamIdstring nullable
sourceUrlstring uri

Capture a public HTTPS website as portable HTML; mutually exclusive with files.

deletePathsstring[]

Explicit paths to remove when publishMode is additive. Omitted paths are retained. Only listed paths are deleted.

immutableAssetPrefixesstring[]

Publisher-owned directory prefixes whose declared files are immutable generation assets. Snapshot publishes retain the matching files from the current generation for exactly one subsequent generation.

sourceMetadataobject

Additional control-plane-only provenance for build/deploy read models.

buildLogstring

Bounded build transcript for deploys that ran a local build before publishing.

publishMode'additive' | 'snapshot'

How to interpret omitted paths in files: additive retains existing paths unless explicitly replaced; snapshot treats files as the complete desired manifest.

emailstring email

Optional expiry-reminder address for anonymous publishes. The server stores it only until the space is claimed or expires, then deletes it. It is never logged.

channel'live' | 'production' nullable

Omit for live publish, use production as an alias for live, or pass null to create a ready version without promotion.

access'private' | 'team' | 'public'

Set the initial root access for this new team-owned Space. Omit this field to use the team's default. Do not set this field with spaceId.

Response

Response for status 201

$schemastring uri

Canonical JSON Schema URL for this response body. The server also sends it in the Link: rel="describedby" response header.

Changes

No recorded changes to this operation across all 1 revision of this API.