API reference

Tags

Tags for people and records: list, create, rename, recolour and delete them, and add or remove them on many items at once.

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

get/workspaces/{workspace_id}/tags

List tags

By name. Not paginated: next_cursor is always null.

NameInRequiredDescription
workspace_idpathyesThe workspace (project) id.

Responses

  • 200 Tags. (TagList)
  • 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)
  • 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"
          },
          "color": {
            "type": "string",
            "description": "Hex colour, for example #4f46e5."
          },
          "person_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "People with this tag (not in Trash)."
          },
          "record_count": {
            "type": "integer",
            "minimum": -9007199254740991,
            "maximum": 9007199254740991,
            "description": "Records with this tag (not in Trash)."
          }
        },
        "required": [
          "id",
          "name",
          "color",
          "person_count",
          "record_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}/tags

Create a tag

A workspace has at most 200 tags. Tags are shared by people and records. 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": "1 to 50 characters after trimming. Unique in the workspace, ignoring case."
    },
    "color": {
      "type": "string",
      "description": "Hex colour: #rgb or #rrggbb."
    }
  },
  "required": [
    "name",
    "color"
  ],
  "additionalProperties": false
}

Responses

  • 201 The created tag. (Tag)
  • 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 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 tag with this name already exists. (ErrorResponse)
  • 422 Validation failed. A bad Idempotency-Key (1-255 characters) is also a 422. Also: Invalid name or colour, or the tag 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)$"
    },
    "name": {
      "type": "string"
    },
    "color": {
      "type": "string",
      "description": "Hex colour, for example #4f46e5."
    },
    "person_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "People with this tag (not in Trash)."
    },
    "record_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Records with this tag (not in Trash)."
    }
  },
  "required": [
    "id",
    "name",
    "color",
    "person_count",
    "record_count"
  ]
}
patch/workspaces/{workspace_id}/tags/{tag_id}

Rename or recolour a tag

The counts in the response are 0; GET tags has them. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

NameInRequiredDescription
workspace_idpathyesThe workspace (project) id.
tag_idpathyesThe tag 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"
    },
    "color": {
      "type": "string"
    }
  },
  "additionalProperties": false
}

Responses

  • 200 The tag. (Tag)
  • 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 tag 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. Also: a tag with this name already exists. (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": {
    "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"
    },
    "color": {
      "type": "string",
      "description": "Hex colour, for example #4f46e5."
    },
    "person_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "People with this tag (not in Trash)."
    },
    "record_count": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Records with this tag (not in Trash)."
    }
  },
  "required": [
    "id",
    "name",
    "color",
    "person_count",
    "record_count"
  ]
}
delete/workspaces/{workspace_id}/tags/{tag_id}

Delete a tag

The tag comes off every person and record that had it. Replays of an Idempotency-Key return the original body and request_id; headers are not replayed.

NameInRequiredDescription
workspace_idpathyesThe workspace (project) id.
tag_idpathyesThe tag 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.

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 tag 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}/tags/apply

Add or remove tags on items

1 to 100 ids of kind, up to 50 tag ids in add and in remove. Adding a tag an item already has changes nothing. All or nothing: every item must be in this workspace and not in Trash, and every tag must be in this workspace. 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": {
    "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)$"
      }
    },
    "add": {
      "description": "Tag ids to add.",
      "maxItems": 50,
      "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)$"
      }
    },
    "remove": {
      "description": "Tag ids to remove.",
      "maxItems": 50,
      "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 Applied. (TagsApplied)
  • 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 or tags 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, neither add nor remove, or the same tag in both. (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
    },
    "added": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Tag assignments created (an existing one is not counted)."
    },
    "removed": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991,
      "description": "Tag assignments removed."
    }
  },
  "required": [
    "ok",
    "added",
    "removed"
  ]
}

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.