Spaces

A space is a named collection of objects. Use spaces to group related items — by project, topic, trip, or any context you want to keep separate. A space can contain up to 10,000 objects, and an object can belong to up to 100 spaces at once.

The space model

Property Type Description
id Uid Unique identifier for the space.
name string Display name of the space. Must be unique across your spaces.
color Color Display color for the space.
created Timestamp When the space was created.
objects SpaceObject[] Objects in this space.

SpaceObject

Property Type Description
id Uid The object's unique identifier.

Actions

Create a space

Creates a new space.

POST /spaces 100 credits

Request body

Property Type Description
name required string Display name for the space. Must be unique across your spaces — duplicate names return 409 Conflict.
color Color A Color value. If omitted, a color is assigned automatically.
Request
{
  "name": "Design research",
  "color": "#e0f2fe"
}
Response 201 Created
{
  "id": "j5K6l7M8n9O0p1Q2r3S4t5",
  "name": "Design research",
  "color": "#e0f2fe",
  "created": "2024-04-08T09:00:00Z"
}

Get a space

Retrieves a single space by its ID, including the list of objects it contains.

GET /spaces/:id 1 credit

Path parameters

Parameter Type Description
id Uid Space to retrieve.
Response 200 OK
{
  "id": "j5K6l7M8n9O0p1Q2r3S4t5",
  "name": "Design research",
  "color": "#e0f2fe",
  "created": "2024-04-08T09:00:00Z",
  "objects": [
    { "id": "a1B2c3D4e5F6g7H8i9J0k1" },
    { "id": "z9Y8x7W6v5U4t3S2r1Q0p9" }
  ]
}

List spaces

Returns all spaces accessible to the authenticated user.

GET /spaces 10 credits

Headers

Header Description
Accept required Either application/json (returns a single array) or application/jsonl (streaming mode — every matching space as newline-delimited JSON).
Response 200 OK
[
  {
    "id": "j5K6l7M8n9O0p1Q2r3S4t5",
    "name": "Design research",
    "color": "#e0f2fe",
    "created": "2024-04-08T09:00:00Z"
  },
  {
    "id": "p2Q3r4S5t6U7v8W9x0Y1z2",
    "name": "Travel inspiration",
    "color": "#fef3c7",
    "created": "2024-03-22T14:10:00Z"
  }
]
Streaming response 200 OK
{"id":"j5K6l7M8n9O0p1Q2r3S4t5","name":"Design research","color":"#e0f2fe","created":"2024-04-08T09:00:00Z"}
{"id":"p2Q3r4S5t6U7v8W9x0Y1z2","name":"Travel inspiration","color":"#fef3c7","created":"2024-03-22T14:10:00Z"}

Update a space

Updates a space's metadata. Only include the fields you want to change — omitted fields are left untouched.

PATCH /spaces/:id 2 credits

Path parameters

Parameter Type Description
id Uid Space to update.

Request body

Property Type Description
name string New display name for the space.
color Color New display color.
Response 200 OK
{
  "id": "j5K6l7M8n9O0p1Q2r3S4t5",
  "name": "Travel inspiration",
  "color": "#fef3c7",
  "created": "2024-04-08T09:00:00Z"
}

Delete a space

Deletes a space. Objects inside are not deleted — they simply lose this space's membership and remain in your mind.

DELETE /spaces/:id Idempotent 1 credit

Path parameters

Parameter Type Description
id Uid Space to delete.
Response 200 OK
{}

Add an object to a space

Adds an object to a space. Idempotent — adding an object that's already in the space is a no-op.

PUT /spaces/:spaceId/objects/:objectId Idempotent 3 credits

Path parameters

Parameter Type Description
spaceId Uid Space to add to.
objectId Uid Object to add.
Response 200 OK
{}

Remove an object from a space

Removes an object from a space. The object itself is not deleted, and remains in any other spaces it belongs to.

DELETE /spaces/:spaceId/objects/:objectId Idempotent 3 credits

Path parameters

Parameter Type Description
spaceId Uid Space to remove from.
objectId Uid Object to remove.
Response 200 OK
{}