API reference

Workspaces

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

Paths are relative to https://kleiobase.com/api/v1.

get/workspaces

List workspaces

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

Responses

  • 200 Workspaces. (WorkspaceList)
  • 401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
  • 403 The account has no paid plan. (ErrorResponse)
  • 429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
  • 500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)
200 response schema
{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
          },
          "name": {
            "type": "string"
          },
          "is_default": {
            "type": "boolean"
          },
          "archived": {
            "type": "boolean",
            "description": "Archived workspaces are read-only: reads work, writes return 409."
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "is_default",
          "archived",
          "created_at"
        ]
      }
    },
    "next_cursor": {
      "description": "Pass as ?cursor to get the next page. Null on the last page.",
      "type": [
        "string",
        "null"
      ]
    }
  },
  "required": [
    "data",
    "next_cursor"
  ]
}
post/workspaces

Create a workspace

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.

NameInRequiredDescription
Idempotency-KeyheadernoMakes 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.
Request body (application/json, required)
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Workspace name, 1 to 80 characters after trimming spaces."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Responses

  • 201 The created workspace. (Workspace)
  • 401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
  • 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). (ErrorResponse)
  • 409 Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
  • 422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
  • 429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
  • 500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)
201 response schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "name": {
      "type": "string"
    },
    "is_default": {
      "type": "boolean"
    },
    "archived": {
      "type": "boolean",
      "description": "Archived workspaces are read-only: reads work, writes return 409."
    },
    "created_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "is_default",
    "archived",
    "created_at"
  ]
}
patch/workspaces/{workspace_id}

Rename a workspace

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

NameInRequiredDescription
workspace_idpathyesThe workspace (project) id.
Idempotency-KeyheadernoMakes 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.
Request body (application/json, required)
{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Workspace name, 1 to 80 characters after trimming spaces."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false
}

Responses

  • 200 The renamed workspace. (Workspace)
  • 401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
  • 403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
  • 404 The workspace does not exist or is not visible to this key's owner. (ErrorResponse)
  • 409 Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
  • 422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
  • 429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
  • 500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)
200 response schema
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "name": {
      "type": "string"
    },
    "is_default": {
      "type": "boolean"
    },
    "archived": {
      "type": "boolean",
      "description": "Archived workspaces are read-only: reads work, writes return 409."
    },
    "created_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "name",
    "is_default",
    "archived",
    "created_at"
  ]
}
post/workspaces/{workspace_id}/archive

Archive a workspace

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.

NameInRequiredDescription
workspace_idpathyesThe workspace (project) id.
Idempotency-KeyheadernoMakes 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.
Request body (application/json)
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Responses

  • 200 Archived. (Ok)
  • 401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
  • 403 The account has no paid plan, or the key is read-only (a read_write key is required). (ErrorResponse)
  • 404 The workspace does not exist or is not visible to this key's owner. (ErrorResponse)
  • 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. (ErrorResponse)
  • 422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
  • 429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
  • 500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)
200 response schema
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ]
}
post/workspaces/{workspace_id}/restore

Restore an archived workspace

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.

NameInRequiredDescription
workspace_idpathyesThe workspace (project) id.
Idempotency-KeyheadernoMakes 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.
Request body (application/json)
{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Responses

  • 200 Restored. (Ok)
  • 401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
  • 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). (ErrorResponse)
  • 404 The workspace does not exist or is not visible to this key's owner. (ErrorResponse)
  • 409 Idempotency-Key was reused with a different request, or a request with it is still in progress. (ErrorResponse)
  • 422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. (ErrorResponse)
  • 429 Rate limit exceeded. Wait the number of seconds in Retry-After. (ErrorResponse)
  • 500 Unexpected error. Retry later and quote request_id if it persists. (ErrorResponse)
200 response schema
{
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ]
}

We use cookies and similar technologies. Essential cookies keep the site working and secure. We only load analytics (PostHog, including masked session replays) and marketing (Meta Pixel and TikTok Pixel) with your consent. See our Privacy Policy.