API overview

Base URL, response envelopes, content types, and a curl walkthrough from credential to published version

Use the Spacefast API to publish files, inspect Spaces, and manage resources within your credential’s permissions. Publishing can return an operation that needs repeated polling before you know the result.

Base URL and versioning

https://api.spacefast.com

Every operation lives under /v1. The version is in the path, so a future /v2 never changes what /v1 returns. The spec that generates the reference is served at https://api.spacefast.com/openapi.json and stamps its own version in info.version (currently 0.3.0).

HEAD works for every GET.

Authentication

One header for API keys, Space credentials, sessions, OAuth tokens, and partner customer JWTs:

curl -sS https://api.spacefast.com/v1/me \
  -H "Authorization: Bearer sfa_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

import { createSpacefastClient } from "@spacefast/sdk";

const client = createSpacefastClient({
  baseUrl: "https://api.spacefast.com",
  apiKey: "<api-key>",
});

const me = await client.get("/v1/me");

Read Authentication for the prefixes, where each credential is created, and which routes refuse which one.

Response envelopes

Success is always an object with a data member. Three shapes cover the whole API.

Shape	When	Example operation
`{ data }`	one resource, or a mutation with no background work	`GET /v1/spaces/{spaceId}`
`{ data, pagination }`	a cursor-paginated list	`GET /v1/spaces/{spaceId}/versions`
`{ data, operation }`	a mutation that can outlive the request	`POST /v1/spaces/{spaceId}/versions/{versionId}/promote`

operation is null when the work finished inside the request. See Operations.

Every JSON body also carries a $schema member naming its JSON Schema, and a Link: <...>; rel="describedby" header pointing at the same document. A strict client-side validator that rejects unknown properties will trip on $schema, so allow it.

Creations answer 201. Deletes answer 204 with no body. Failures are RFC 9457 problem documents with Content-Type: application/problem+json, described in Errors.

Content types

Send application/json on every request body. POST /v1/publish is the exception. It also accepts multipart/form-data, a raw text/html or application/octet-stream single file, and zip/tar/gzip project archives.

Every response carries X-Request-Id. It equals the requestId in a problem document, and it is the value to quote when you ask for help.

Publish with curl

Check the credential

curl -sS https://api.spacefast.com/v1/me \
  -H "Authorization: Bearer $SPACEFAST_API_KEY"

Returns the authenticated subject with its team memberships. Copy the teamId you want to publish under.

Create a Space

curl -sS -X POST https://api.spacefast.com/v1/spaces \
  -H "Authorization: Bearer $SPACEFAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"team_example","slug":"marketing-site","title":"Marketing site","access":"private"}'

201 { data: { space, access, claim? } }. The Space id looks like spc_4a7f9c2e8b1d0a6f5c3e9d2b7a1f8e4c.

Publish files

curl -sS -X POST "https://api.spacefast.com/v1/publish?async=1" \
  -H "Authorization: Bearer $SPACEFAST_API_KEY" \
  -H "Idempotency-Key: 01J8ZQ7WYX3M4N5P6R7S8T9V0W" \
  -F "spaceId=spc_4a7f9c2e8b1d0a6f5c3e9d2b7a1f8e4c" \
  -F "files=@index.html"

The receipt names what to do next:

{
  "data": {
    "space": { "id": "spc_4a7f...", "slug": "marketing-site", "liveUrl": "https://marketing-site.space.fast" },
    "version": { "id": "ver_8c1d...", "status": "finalizing", "number": 7, "immutableUrl": null },
    "next": { "action": "poll", "url": "/v1/operations/op_2f6a...", "retryAfter": 1 },
    "operation": { "id": "op_2f6a...", "kind": "version_finalize", "status": "running" }
  }
}

Drop async=1 and the request waits for the finalize instead, returning next.action: "done".

Poll until it settles

curl -sS https://api.spacefast.com/v1/operations/op_2f6a9d4c1e7b0a3f8d5c2e6b9a4f1d7c \
  -H "Authorization: Bearer $SPACEFAST_API_KEY"

Stop when data.status is succeeded, failed, or canceled. Then read space.liveUrl and version.immutableUrl.

Where to next

Authentication

API keys, Space keys, machine credentials, OAuth scopes.

Errors

Problem documents, the stable code, and every code the API can return.

Pagination

Cursor paging, endpoint defaults, and other list shapes.

Rate limits

Per-credential and per-IP budgets, and what a 429 carries.

Idempotency

Make any POST safe to retry.

Operations

Async work: the handle, the states, the polling loop.

Webhooks

Signed event delivery, retries, and redelivery.

TypeScript SDK

@spacefast/sdk, typed against this spec.

API reference

Every operation, generated from the spec.

Find documentation

GET /v1/docs/search searches the published documentation without authentication. Set q to a question for ranked results, or to an exact page slug to read the full page. An empty q lists pages; tier and kind narrow the result. Continue with nextOffset while hasMore is true.

POST /v1/docs/ask streams an answer grounded in the documentation.

Connect external tools

Connectors make OpenAPI, GraphQL, and remote MCP tools available to a team. Register a connector, connect an account, then choose which tools a policy allows. Account credentials remain server-side.

Use the connector reference to register a source, create a connection, and run a tool or program. A policy can require approval before a run proceeds. Read the run’s result before reporting success.