# Workspaces endpoints

List, create, rename, archive and restore your workspaces. Every other resource lives under one.

Paths are relative to https://kleiobase.com/api/v1. Request and response schemas are in the OpenAPI document at https://kleiobase.com/api/v1/openapi.json.

## List workspaces

`GET /workspaces`

Workspaces the key's owner owns. Not paginated: next_cursor is always null.

Responses:

- `200`: Workspaces.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Create a workspace

`POST /workspaces`

Your plan's limit on active workspaces applies (archived workspaces do not count). Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `201`: The created workspace.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required). Also: the plan's workspace limit is reached (details has limit, used and plan).
- `409`: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Rename a workspace

`PATCH /workspaces/{workspace_id}`

Archived workspaces can be renamed too. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: The renamed workspace.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner.
- `409`: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Archive a workspace

`POST /workspaces/{workspace_id}/archive`

An archived workspace is read-only: reads work, writes return 409, and it does not count toward your plan's workspace limit. Nothing is deleted. Restore it with POST .../restore. Archiving a workspace that is already archived changes nothing. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: Archived.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required).
- `404`: The workspace does not exist or is not visible to this key's owner.
- `409`: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: the default workspace can't be archived.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

## Restore an archived workspace

`POST /workspaces/{workspace_id}/restore`

Your plan's limit on active workspaces is checked again. Restoring a workspace that is not archived changes nothing. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Parameters:

- `workspace_id` (path, required): The workspace (project) id.
- `Idempotency-Key` (header, optional): Makes the write safe to retry (1-255 characters, kept 24 hours). Same key and same request replays the original response; a different request with the same key is a 409.

Takes a request body; see the OpenAPI document for its schema.

Responses:

- `200`: Restored.
- `401`: Missing, malformed, unknown or revoked API key.
- `403`: The account has no paid plan, or the key is read-only (a read_write key is required). Also: the plan's workspace limit is reached (details has limit, used and plan).
- `404`: The workspace does not exist or is not visible to this key's owner.
- `409`: Idempotency-Key was reused with a different request, or a request with it is still in progress.
- `422`: Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422.
- `429`: Rate limit exceeded. Wait the number of seconds in Retry-After.
- `500`: Unexpected error. Retry later and quote request_id if it persists.

Canonical: https://kleiobase.com/developers/docs/reference/workspaces