Skip to content
Day Planner

Spaces

Spaces are the top-level areas of your planner; each one holds projects, tasks and documents. One space per account is the default, and the delete endpoint refuses to remove it. These endpoints act on your own spaces only: an id belonging to anyone else returns 404 Not Found.

List spaces

Section titled “List spaces”

Returns all your spaces with their projects and record counts.

GET /api/spaces

No query parameters are needed.

Response

Section titled “Response”

A bare JSON array of spaces:

[
  {
    "id": "0e5a7c3b-2f16-4d98-b7a4-8c1e3f5d9b02",
    "userId": "6f0d2a9b-1c74-4e8f-8a3b-5c9d0e2f6a71",
    "name": "Work",
    "color": "#3B82F6",
    "icon": "briefcase",
    "isDefault": false,
    "sortOrder": 1,
    "createdAt": "2026-09-28T22:30:00.000Z",
    "updatedAt": "2026-09-28T22:30:00.000Z",
    "projects": [
      { "id": "b7d3e9a1-5c02-4f47-9a86-1d6b0e4c8a53", "name": "Website refresh", "color": "#10B981", "_count": { "tasks": 6 } }
    ],
    "_count": { "tasks": 8, "documents": 2 }
  }
]

Spaces come back ordered by sortOrder. Each space’s projects gives its projects with their task counts, and _count gives the numbers of tasks and documents in the space.

Status codes

Section titled “Status codes”
Code When
200 OK the list returned
401 Unauthorized no valid session or API key

Create a space

Section titled “Create a space”

Creates one space in your account.

POST /api/spaces

Send these fields in the JSON body:

Body parameters

Section titled “Body parameters”
Name Type Required Description
name string Yes Space name, 1–100 characters
color string No Colour such as #6B7280; defaults to #6B7280
icon string No Icon name

New spaces are never the default and start at sortOrder 0.

Response

Section titled “Response”

The new space comes back with 201 Created:

{
  "id": "0e5a7c3b-2f16-4d98-b7a4-8c1e3f5d9b02",
  "userId": "6f0d2a9b-1c74-4e8f-8a3b-5c9d0e2f6a71",
  "name": "Work",
  "color": "#3B82F6",
  "icon": "briefcase",
  "isDefault": false,
  "sortOrder": 0,
  "createdAt": "2026-09-28T22:30:00.000Z",
  "updatedAt": "2026-09-28T22:30:00.000Z"
}

The response is the space row on its own; the project and task counts appear in the space list.

Status codes

Section titled “Status codes”
Code When
201 Created the space was created
400 Bad Request the body failed validation (Validation failed)
401 Unauthorized no valid session or API key

Update a space

Section titled “Update a space”

Changes fields of one space. Omit the fields you want to keep.

PATCH /api/spaces/{id}

Send only the fields to change in the JSON body:

Body parameters

Section titled “Body parameters”
Name Type Required Description
name string No Space name, 1–100 characters
color string No Colour such as #3B82F6
icon string No Icon name
sortOrder number No Position in the space list

The isDefault flag can’t be changed through the API.

Response

Section titled “Response”

The updated space comes back as one JSON object:

{
  "id": "0e5a7c3b-2f16-4d98-b7a4-8c1e3f5d9b02",
  "userId": "6f0d2a9b-1c74-4e8f-8a3b-5c9d0e2f6a71",
  "name": "Design",
  "color": "#8B5CF6",
  "icon": "palette",
  "isDefault": false,
  "sortOrder": 2,
  "createdAt": "2026-09-28T22:30:00.000Z",
  "updatedAt": "2026-09-30T03:02:44.000Z"
}

Only the fields you send change; the rest keep their old values.

Status codes

Section titled “Status codes”
Code When
200 OK the space was updated
400 Bad Request the body failed validation (Validation failed)
401 Unauthorized no valid session or API key
404 Not Found no space with that id belongs to you (Space not found)

Delete a space

Section titled “Delete a space”

Deletes one space outright, after moving its contents out.

DELETE /api/spaces/{id}

No body is needed.

Deleting a space detaches everything inside it: its tasks, projects and documents keep existing with no space, their spaceId becoming null. The default space can’t be deleted, so that request gets 400 Bad Request (Cannot delete default space).

Response

Section titled “Response”

The endpoint confirms the change:

{
  "success": true
}

The space row is gone for good; the tasks and projects that were in it remain.

Status codes

Section titled “Status codes”
Code When
200 OK the space was deleted
400 Bad Request the space is the default one (Cannot delete default space)
401 Unauthorized no valid session or API key
404 Not Found no space with that id belongs to you (Space not found)

See also

Section titled “See also”