API reference

Trash

Trashed people and records: list, restore or permanently delete them.

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

get/workspaces/{workspace_id}/trash

List the Trash

Newest deletion first.

Name	In	Required	Description
workspace_id	path	yes	The workspace (project) id.
limit	query	no	Page size. Default 25, max 100.
cursor	query	no	The next_cursor of the previous page. Opaque.
type	query	no	people or records (default both).

Responses

200 A page of trashed items. (TrashList)
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 limit, cursor or type. (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)$"
          },
          "type": {
            "type": "string",
            "enum": [
              "person",
              "record"
            ]
          },
          "name": {
            "type": "string"
          },
          "deleted_at": {
            "description": "When it was moved to the Trash.",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "id",
          "type",
          "name",
          "deleted_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/{workspace_id}/trash/restore

Restore from Trash

At least one id, at most 100 in total. All or nothing: every id must be in this workspace's Trash. A restored person brings their trashed linked records back with 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.
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": {
    "people_ids": {
      "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)$"
      }
    },
    "record_ids": {
      "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)$"
      }
    }
  },
  "additionalProperties": false
}

Responses

200 Restored. (TrashRestored)
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: An item does not exist, is not visible, or is not 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
    },
    "restored_person_ids": {
      "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)$"
      }
    },
    "restored_record_ids": {
      "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)$"
      },
      "description": "Every record brought back: the ones asked for plus the trashed records linked to a restored person."
    }
  },
  "required": [
    "ok",
    "restored_person_ids",
    "restored_record_ids"
  ]
}

post/workspaces/{workspace_id}/trash/delete

Permanently delete from Trash

Cannot be undone. Only items already in Trash: at least one id, at most 100 in total. All or nothing: every id must be in this workspace's Trash. Record image files are deleted too. 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": {
    "people_ids": {
      "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)$"
      }
    },
    "record_ids": {
      "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)$"
      }
    }
  },
  "additionalProperties": false
}

Responses

200 Deleted. (TrashDeleted)
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: An item does not exist, is not visible, or is not 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. Also: A person still has people merged into them who are not in the request (details.merged_person_ids). Nothing is deleted. (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
    },
    "deleted_person_ids": {
      "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)$"
      }
    },
    "deleted_record_ids": {
      "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": [
    "ok",
    "deleted_person_ids",
    "deleted_record_ids"
  ]
}