Tags

A tag is a free-form label you attach to recordings — vip, callback-requested, complaint. Tags are yours to define; nothing in the analysis pipeline writes them.

Tags belong to a recording project, not to your account.

A tag called vip in project 12 and a tag called vip in project 13 are two separate rows with two different ids. Creating vip in one project does not make it available in the other, and deleting it from one leaves the other untouched.

This means a tag_id is only meaningful alongside its project. If you cache tag ids client-side, cache them per project.

Scopes

API key scope	Allowed operations
Account-wide	Full access to tags in any project in the account. Every request must name the project via `project_id`.
Project-scoped	Access restricted to the bound project. `project_id` may be omitted, and must match the bound project if supplied.

Endpoints

List TagsGET/tags

Enumerate the tags defined in a project, ordered by name.

Create TagPOST/tags

Define a new tag in a project. Idempotent on name.

Delete TagDELETE/tags/:id

Remove a tag and detach it from every recording.

Attaching tags to recordings

You do not need these endpoints to tag a recording. Both Create Recording and Update Recording accept a tags array of names, resolved against the recording’s own project and created there if they don’t exist yet:


curl -X POST "https://api.identitycall.ai/api/v1/public/recordings" \
  -H "Authorization: Bearer $IDENTITYCALL_API_KEY" \
  -F "file=@call.mp3" \
  -F "project_id=12" \
  -F "tags[]=vip" \
  -F "tags[]=callback-requested"

Use POST /tags when you want to pre-define a project’s vocabulary — for example to populate a dropdown in your own UI — rather than letting it accumulate from uploads.

Colours

Colours are assigned automatically from a fixed ten-colour palette, and cannot be set through the API. Each project works through the palette independently, so a project’s first tag is always the same colour. Past ten tags in one project, colours start repeating.

See the OpenAPI spec for the full field list.