API reference

Tags

Tags are colored labels shared by the whole workspace. Leads, contacts and companies carry them by name; the catalog holds each tag's name and color.

How tags work

A record's tags field is a list of tag names, the same on leads, contacts and companies. Send names when you create or update a record: a name that is not in the catalog yet is added to it with an automatic color, and a name that differs only in case (vip for VIP) is stored the way the catalog spells it.

Going over a limit answers 422 with a message in fields.tags (bulk changes: fields["action.tags"]), and nothing is changed. A record that already had more than 10 tags from older data keeps them: it can drop tags but not add new ones until it is under the limit. Website forms and imports never fail because of tags: a tag the catalog can't take is left out (imports report it as a row warning).

Anyone who can edit a record can tag it. New catalog tags can be created by every member who can edit records, unless an admin turned on Only admins create tags (admins_only_create); then others pick existing tags only. Renaming, recoloring, merging and deleting tags need an owner or admin, or an API key with tags:manage.

Filter by tag with tag:vip, -tag:spam, tag:vip,hot (any of them) and has:tag with the query endpoint, on leads, contacts and companies.

The tag object

{
  "id": "tag_01j8z7f2k4m6p8r0t2v4x6z8b0",
  "name": "VIP",
  "color": "amber",
  "created_at": "2026-09-28T09:12:44.10Z",
  "usage": { "leads": 42, "contacts": 17, "companies": 3 }
}

List tags

All tags of the workspace by name (at most 200, so there is no pagination). Add usage=1 for the counts. The answer also says what the caller may do:

{
  "data": [ { "id": "tag_…", "name": "VIP", "color": "amber", "created_at": "…" } ],
  "settings": { "admins_only_create": false },
  "limits": { "per_record": 10, "per_workspace": 200, "name_length": 32 },
  "can_create": true,
  "can_manage": false
}

curl "https://api.kweko.uz/v1/tags?usage=1" \
  -H "Authorization: Bearer $KWEKO_API_KEY"

Create a tag

Answers 201 with the new tag, or 200 with the existing tag when the name is already in the catalog (in any case), so it is safe to retry. 403 tags_admins_only when only admins may create tags, 409 tag_limit when the workspace has 200 tags.

curl https://api.kweko.uz/v1/tags \
  -H "Authorization: Bearer $KWEKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Wholesale"}'

Rename or recolor

Send name, color or both. A rename updates every lead, contact and company with the tag, the website forms that add it, and the automations and saved filters that name it, in one step. The answer has the tag and affected, the number of records changed per entity. Renaming onto the name of another tag answers 409 tag_exists with its tag_id: merge the two instead.

{ "tag": { "id": "tag_…", "name": "Key client", "color": "amber", "created_at": "…" }, "affected": { "leads": 42, "contacts": 17, "companies": 3 } }

Merge

Body: {"into": "tag_…"}. Every record with this tag gets the into tag instead (a record that had both keeps one), forms, automations and saved filters follow, and this tag is deleted. Answers with the into tag and affected.

Delete

Removes the tag from every record and website form, then from the catalog. Answers {"ok": true, "id": "tag_…", "affected": {…}}. Automations and filters that name a deleted tag stay as they are and match nothing; an automation that adds the tag creates it again.

Settings

Body: {"admins_only_create": true} lets only owners and admins (and keys with tags:manage) create new tags.

Tag many records at once

Bulk changes (POST /v1/bulk/{leads|contacts|companies}/run) take three tag actions, each undoable for 24 hours:

A record that would go over 10 tags is skipped with the reason too_many_tags; the others change.