API reference

Folders

Folders for people and records: list, create, rename, move and delete them, and move items into one.

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

get/workspaces/{workspace_id}/folders

List folders

A flat list; build the tree from parent_id. People and records have separate folder trees. Not paginated: next_cursor is always null.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
kind	query	no	Only folders of people or of records.

Responses

200 Folders. (FolderList)
401 Missing, malformed, unknown or revoked API key. (ErrorResponse)
403 The account has no paid plan. (ErrorResponse)
404 The workspace does not exist or is not visible to this key's owner. (ErrorResponse)
422 Invalid kind. (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)$"
          },
          "parent_id": {
            "anyOf": [
              {
                "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)$"
              },
              {
                "type": "null"
              }
            ],
            "description": "The folder this one sits in. Null at the top level."
          },
          "kind": {
            "type": "string",
            "enum": [
              "people",
              "records"
            ],
            "description": "What the folder holds, or what the ids are: people or records."
          },
          "name": {
            "type": "string"
          },
          "item_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "People or records directly in this folder (not in Trash)."
          },
          "child_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Folders directly inside this one."
          }
        },
        "required": [
          "id",
          "parent_id",
          "kind",
          "name",
          "item_count",
          "child_count"
        ]
      }
    },
    "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/{workspace_id}/folders

Create a folder

Folders nest up to 10 levels; a workspace has at most 500. Names are unique among siblings, ignoring case. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
Idempotency-Key	header	no	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.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "people",
        "records"
      ],
      "description": "What the folder holds, or what the ids are: people or records."
    },
    "name": {
      "type": "string",
      "description": "1 to 100 characters after trimming."
    },
    "parent_id": {
      "description": "Create it inside this folder (same kind). Omit or null for the top level.",
      "anyOf": [
        {
          "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)$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "kind",
    "name"
  ],
  "additionalProperties": false
}

Responses

201 The created folder. (Folder)
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. Also: parent_id is not a folder in this workspace. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: a sibling folder already has this name. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid name, a parent of the other kind, too deep, or the folder limit is reached. (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)$"
    },
    "parent_id": {
      "anyOf": [
        {
          "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)$"
        },
        {
          "type": "null"
        }
      ],
      "description": "The folder this one sits in. Null at the top level."
    },
    "kind": {
      "type": "string",
      "enum": [
        "people",
        "records"
      ],
      "description": "What the folder holds, or what the ids are: people or records."
    },
    "name": {
      "type": "string"
    },
    "item_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "People or records directly in this folder (not in Trash)."
    },
    "child_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Folders directly inside this one."
    }
  },
  "required": [
    "id",
    "parent_id",
    "kind",
    "name",
    "item_count",
    "child_count"
  ]
}

patch/workspaces/{workspace_id}/folders/{folder_id}

Rename or move a folder

parent_id null moves it to the top level. The counts in the response are 0; GET folders has them. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
folder_id	path	yes	The folder id.
Idempotency-Key	header	no	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.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "name": {
      "description": "1 to 100 characters after trimming.",
      "type": "string"
    },
    "parent_id": {
      "description": "Move it inside this folder. Null moves it to the top level.",
      "anyOf": [
        {
          "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)$"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "additionalProperties": false
}

Responses

200 The folder. (Folder)
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. Also: The folder or parent_id is not a folder in this workspace. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: Idempotency-Key was reused with a different request, or a request with it is still in progress. Also: a sibling folder already has this name. (ErrorResponse)
422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid body, a parent of the other kind, too deep, or a move into the folder itself or one of its own subfolders. (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)$"
    },
    "parent_id": {
      "anyOf": [
        {
          "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)$"
        },
        {
          "type": "null"
        }
      ],
      "description": "The folder this one sits in. Null at the top level."
    },
    "kind": {
      "type": "string",
      "enum": [
        "people",
        "records"
      ],
      "description": "What the folder holds, or what the ids are: people or records."
    },
    "name": {
      "type": "string"
    },
    "item_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "People or records directly in this folder (not in Trash)."
    },
    "child_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Folders directly inside this one."
    }
  },
  "required": [
    "id",
    "parent_id",
    "kind",
    "name",
    "item_count",
    "child_count"
  ]
}

delete/workspaces/{workspace_id}/folders/{folder_id}

Delete a folder

Only the folder is deleted: its subfolders and items move up into its parent (or to the top level). Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
folder_id	path	yes	The folder id.
Idempotency-Key	header	no	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.

Responses

200 Deleted. (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. Also: The folder is not in this workspace. (ErrorResponse)
409 The workspace is archived (writes are refused). Also: 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"
  ]
}

post/workspaces/{workspace_id}/folders/{folder_id}/items

Move items into a folder

1 to 100 ids of kind. An item is in at most one folder, so it leaves its current folder. All or nothing: every id must be a person or record of that kind in this workspace and not in Trash. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
folder_id	path	yes	The folder id.
Idempotency-Key	header	no	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.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "people",
        "records"
      ],
      "description": "What the folder holds, or what the ids are: people or records."
    },
    "ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "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)$"
      }
    }
  },
  "required": [
    "kind",
    "ids"
  ],
  "additionalProperties": false
}

Responses

200 Moved. (FolderItemsMoved)
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. Also: The folder, or one of the items, is not in this workspace (or the item is in Trash). (ErrorResponse)
409 The workspace is archived (writes are refused). Also: 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. Also: Invalid body, or kind does not match the folder. (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
    },
    "moved": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many items were moved."
    }
  },
  "required": [
    "ok",
    "moved"
  ]
}

post/workspaces/{workspace_id}/folders/unfile

Move items to the top level

Takes 1 to 100 people or records out of their folder, as Top level in the app's Move to folder. An item already at the top level stays there. All or nothing: every id must be a person or record of that kind in this workspace and not in Trash. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
Idempotency-Key	header	no	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.

Request body (application/json, required)

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "people",
        "records"
      ],
      "description": "What the folder holds, or what the ids are: people or records."
    },
    "ids": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "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)$"
      }
    }
  },
  "required": [
    "kind",
    "ids"
  ],
  "additionalProperties": false
}

Responses

200 Moved. (FolderItemsMoved)
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. Also: One of the items is not in this workspace (or is in Trash). (ErrorResponse)
409 The workspace is archived (writes are refused). Also: 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. Also: Invalid body. (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
    },
    "moved": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "How many items were moved."
    }
  },
  "required": [
    "ok",
    "moved"
  ]
}