List Tags
Retrieve the tags defined in a recording project.
GET
https://api.identitycall.ai/api/v1/public/tagsReturns the project's tags ordered by name, with a usage count for each.
Requires read permission
Scope
| API key scope | Returned tags |
|---|---|
| Account-wide | Tags in the project named by project_id. The parameter is required. |
| Project-scoped | Tags in the bound project. project_id may be omitted. |
Query Parameters
Query Parameters
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
project_id | integer | No | - | The project whose tags to list. Required for account-wide keys; optional for project-scoped keys, which may only pass their own project id. |
Request
cURL
curl -X GET "https://api.identitycall.ai/api/v1/public/tags?project_id=12" \
-H "Authorization: Bearer $IDENTITYCALL_API_KEY"Response
Response200 OK
{
"data": [
{
"id": 7,
"name": "callback-requested",
"color": "#F59E0B",
"project_id": 12,
"recordings_count": 34
},
{
"id": 9,
"name": "complaint",
"color": "#10B981",
"project_id": 12,
"recordings_count": 8
},
{
"id": 4,
"name": "vip",
"color": "#EF4444",
"project_id": 12,
"recordings_count": 112
}
]
}Response Fields
| Field | Type | Description |
|---|---|---|
id | integer | Unique tag ID. Only meaningful within its project. |
name | string | The tag name |
color | string | Hex colour assigned automatically from a fixed palette |
project_id | integer | The recording project this tag belongs to |
recordings_count | integer | How many recordings currently carry this tag |
Filtering recordings by tag
Pass the ids to List Recordings as tag_ids[]. A recording matches if it carries any of the given tags:
curl -X GET "https://api.identitycall.ai/api/v1/public/recordings?tag_ids[]=4&tag_ids[]=7" \
-H "Authorization: Bearer $IDENTITYCALL_API_KEY"Errors
| Status | Error | Description |
|---|---|---|
| 401 | “Invalid API key” | Missing or unrecognized bearer token |
| 403 | “Read permission required” | API key lacks read permission |
| 403 | “project_id does not match this API key’s project” | A project-scoped key passed a different project’s id |
| 404 | “Project not found” | The project does not exist, or belongs to another account |
| 422 | “project_id is required for account-wide API keys” | An account-wide key omitted project_id |