CUBSTER Join the waitlist
DOCS / TAGS

Tags

Tags are workspace-wide, not per-service: an asset, a transcript, a diagram, an artifact, a chart, and a query all carry the same tags: string[], validated by the same rule everywhere. There is one place to ask what tags a workspace uses (GET /api/v1/tags) and one place to see everything carrying a given tag, across all six types at once (GET /api/v1/tagged).

What a tag is

A plain string, nothing more — there is no key/value schema and no grouping. project:cubster is a valid tag; the colon is a naming convention you can adopt, but the server never parses it or gives it any meaning of its own.

The tag rule

One shared rule, enforced identically everywhere a tag can be written:

  • 1–40 characters after trimming.
  • No control characters — checked on the string as sent, before the trim.
  • At most 20 tags per object.
  • Case is preserved and matching is exact — Docs and docs are two different tags. There's no case-insensitive filter and no lowercasing on write.

A violation is a 400 naming the exact problem, e.g. tags must be an array of at most 20 strings or tags[0] must not contain control characters.

Setting tags

Every create route takes an optional tags field: POST /api/v1/uploads and POST /api/v1/transcribe (multipart — a comma-separated string or a JSON-array string), POST /api/v1/{diagrams,artifacts,charts,queries} (a JSON array), and POST /api/v1/realtime/sessions (a JSON array, carried in the signed session token and copied onto the transcript the session produces — see Realtime).

Retagging afterward never publishes a new version — it only ever touches tags: PATCH /api/v1/assets/:id, PATCH /api/v1/transcripts/:id (alongside an optional displayName), and PATCH /api/v1/{diagrams,artifacts,charts}/:slug. For a diagram, artifact, or chart, latestVersion and the stored document are untouched — a retag is not an edit. A query has no version to preserve in the first place, so its tags are edited through the same PATCH /api/v1/queries/:slug that edits its title and definition — { tags } alone is a valid body. Sending a visibility key on any of the four document routes gets the same verbatim refusal as create/update: 400 { "error": "visibility is not accepted here; change it in the dashboard" } — a query has no visibility at all, so this refusal doesn't apply to it.

$ curl -X PATCH https://app.cubster.dev/api/v1/charts/wN4jC8pXaTsQ \
  -H "Authorization: Bearer $CUBSTER_API_KEY" -H "Content-Type: application/json" \
  -d '{"tags": ["repo", "weekly"]}'
$ cubster tags set chart wN4jC8pXaTsQ --tag repo --tag weekly
$ cubster tags set transcript <id> --clear
Vocabulary & cross-type lookup

GET /api/v1/tags?includeArchived= — the workspace's tag vocabulary: one entry per tag, its total count, and a breakdown by type. There is no tags service — what a caller can see comes from the OTHER services it already holds. A session sees all six types; a key sees only the types whose backing service (assets, transcription, diagrams, artifacts, charts, queries) is in its own service scope. A key matching none of them still gets 200 { "tags": [] }, never a 403.

GET /api/v1/tagged?tag=<t>&includeArchived= — every object of a visible type carrying <t>, newest-first. It's a query param rather than /tags/:tag on purpose: a tag can contain / or :, and a path segment would need encoding rules the SDK and CLI would then have to get right — a query param needs none. At most 100 assets and 100 transcripts per response; documents are not capped.

$ cubster tags ls
TAG COUNT BY TYPE
auth 7 diagram 3, artifact 4
$ cubster tags find auth
TYPE ID/SLUG TITLE UPDATED
diagram aB3xQ9zK7mN2 Upload pipeline 2026-09-20T12:00:00.000Z

See the CLI reference for cubster tags ls|find|set, and the REST reference for the full endpoint list.

The dashboard

/tags lists the vocabulary with counts; /tags?tag=X lists everything tagged X across all six types, each row a type pill linking into its own detail page — a query's pill links to its detail panel on /queries/:slug. Assets, Documents, and Transcripts each filter their own list from the same tag dropdown, fed by the workspace vocabulary — Assets is multi-select (?tags=a,b), Documents and Transcripts are single-select (?tag=, replacing on each pick). Each object's detail panel — the transcript panel and the three document panels — has a tag editor that saves through the same PATCH routes above. There are no thumbnails and no bulk edit on the tags page — it's a plain list, on purpose.