---
title: "Claim a space with its key"
method: POST
path: "/v1/claim"
tags: ["Publishing"]
---

# Claim a space with its key

`POST /v1/claim`

## Request

- Base URL: `https://api.spacefast.com`
- URL: `https://api.spacefast.com/v1/claim`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer

Moves an anonymously published Space into a team of the signed-in user, or returns the one decision still needed: sign-in, team choice, or agent consent. Send the Space key saved by the client that published it, plus any team or consent the user chose, and repeat until the response is `claimed`. A claimed Space no longer expires. The server checks eligibility. Never ask the user to paste a Space key into chat.

## Request body

- object
  - `key` string: The space key, when not sent as bearer auth. Browser claim pages send it here after reading the /claim#<key> fragment.
  - `teamId` string: Team receiving the space. Inferred when the caller has exactly one writable team; otherwise the response answers `team_required` with the choices.
  - `agentContinuation` boolean: User consent to keep the publishing agent authorized after the claim. Required (true or false) when the space is continuation-eligible; the server independently proves eligibility, so consent cannot grant continuation to an ineligible space.

## 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
    - `state` 'unclaimed' | 'claimed', required
    - `action` 'claimed' | 'login_required' | 'team_required' | 'consent_required', required
    - `space` object, required
      - `id` string, required
      - `title` string, required
      - `liveUrl` string, nullable, required
      - `createdAt` string, date-time, nullable, required
    - `claim` object, required
      - `expiresAt` string, date-time, nullable, required
      - `claimedAt` string, date-time, nullable, required
    - `access` object: The space's reusable Open link, returned once the claim commits so the page can open the (private-by-default) site. Pre-claim callers already hold the key and its door URL.
      - `url` string, uri, required
      - `token` string, required
      - `expiresAt` string, date-time, nullable, required
    - `continuation` object, required: Server-authoritative continuation eligibility and claim result.
      - `eligible` boolean, required: Server-proven continuation eligibility. Eligible means the publish intent records an originating agent that holds the space key, the one-time exchange is unredeemed, and a safe secretless return exists. Only then can the UI offer continuation.
      - `granted` boolean, required: Whether the claim left the one-time continuation exchange open for the originating agent.
    - `teams` object[]
      - `id` string, required
      - `slug` string, required
      - `name` string, required
    - `sharing` object, required
      - `people` object[], required
        - `id` string, required
        - `displayName` string, required
        - `status` 'pending' | 'accepted', required
        - `grants` object[], required
          - `scope` string, required
          - `role` 'viewer' | 'commenter' | 'editor' | 'manager', required
      - `links` object[], required
        - `id` string, required
        - `revision` integer, required
        - `name` string, required
        - `landingPath` string, required
        - `scopes` string[], required
        - `expiresAt` string, date-time, nullable, required

## 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)