Tags
List, create, read, update, and delete tags via the API.
Tags API
Manage tags and organize them into groups. All endpoints require an API token with the appropriate tags.* ability.
List Tags
GET /api/v1/tags — Permission: tags.view
Returns tags sorted alphabetically by name.
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
search | string | No | Search by tag name (case-insensitive partial match) |
per_page | integer | No | Results per page, 1–100 (default: 25) |
Example Request
curl -X GET "https://your-domain.com/api/v1/tags?search=vip" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"const response = await fetch("https://your-domain.com/api/v1/tags?search=vip", {
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
});
const data = await response.json();$ch = curl_init('https://your-domain.com/api/v1/tags?search=vip');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.get(
"https://your-domain.com/api/v1/tags?search=vip",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
)
data = response.json()Example Response
{
"data": [
{
"id": 3,
"name": "VIP",
"slug": "vip",
"color": "blue",
"group_id": 1,
"group_name": "Priority",
"created_at": "2025-01-10T08:00:00.000000Z",
"updated_at": "2025-01-10T08:00:00.000000Z"
}
],
"meta": { "current_page": 1, "last_page": 1, "per_page": 25, "total": 1 },
"links": { "first": "...", "last": "...", "prev": null, "next": null }
}Create Tag
POST /api/v1/tags — Permission: tags.create
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Yes | Tag name (max 255). Slug is auto-generated. |
color | string | No | Tag color (max 50, defaults to gray) |
tag_group_id | integer | No | ID of a tag group to organize this tag under |
Example Request
curl -X POST "https://your-domain.com/api/v1/tags" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"name": "Enterprise",
"color": "purple",
"tag_group_id": 1
}'const response = await fetch("https://your-domain.com/api/v1/tags", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json",
"Content-Type": "application/json"
},
body: JSON.stringify({
name: "Enterprise",
color: "purple",
tag_group_id: 1
})
});
const data = await response.json();$ch = curl_init('https://your-domain.com/api/v1/tags');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Accept: application/json',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Enterprise',
'color' => 'purple',
'tag_group_id' => 1,
]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.post(
"https://your-domain.com/api/v1/tags",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
},
json={
"name": "Enterprise",
"color": "purple",
"tag_group_id": 1
}
)
data = response.json()Example Response 201 Created
{
"data": {
"id": 15,
"name": "Enterprise",
"slug": "enterprise",
"color": "purple",
"group_id": 1,
"group_name": "Priority",
"created_at": "2025-03-20T14:00:00.000000Z",
"updated_at": "2025-03-20T14:00:00.000000Z"
}
}Get Tag
GET /api/v1/tags/{id} — Permission: tags.view
Example Request
curl -X GET "https://your-domain.com/api/v1/tags/3" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"const response = await fetch("https://your-domain.com/api/v1/tags/3", {
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
});
const data = await response.json();$ch = curl_init('https://your-domain.com/api/v1/tags/3');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.get(
"https://your-domain.com/api/v1/tags/3",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
)
data = response.json()Returns the same shape as a single item in the list response.
Update Tag
PUT /api/v1/tags/{id} — Permission: tags.edit
Send only the fields you want to change. Updating the name automatically regenerates the slug.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
name | string | Sometimes | Tag name (max 255) |
color | string | No | Tag color (max 50) |
tag_group_id | integer | No | Tag group ID (set to null to remove from group) |
Example Request
curl -X PUT "https://your-domain.com/api/v1/tags/15" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"color": "gold"
}'const response = await fetch("https://your-domain.com/api/v1/tags/15", {
method: "PUT",
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json",
"Content-Type": "application/json"
},
body: JSON.stringify({
color: "gold"
})
});
const data = await response.json();$ch = curl_init('https://your-domain.com/api/v1/tags/15');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'PUT',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Accept: application/json',
'Content-Type: application/json',
],
CURLOPT_POSTFIELDS => json_encode([
'color' => 'gold',
]),
]);
$response = curl_exec($ch);
curl_close($ch);
$data = json_decode($response, true);import requests
response = requests.put(
"https://your-domain.com/api/v1/tags/15",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
},
json={
"color": "gold"
}
)
data = response.json()Delete Tag
DELETE /api/v1/tags/{id} — Permission: tags.delete
Example Request
curl -X DELETE "https://your-domain.com/api/v1/tags/15" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Accept: application/json"const response = await fetch("https://your-domain.com/api/v1/tags/15", {
method: "DELETE",
headers: {
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
});
// 204 No Content$ch = curl_init('https://your-domain.com/api/v1/tags/15');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'DELETE',
CURLOPT_HTTPHEADER => [
'Authorization: Bearer YOUR_API_TOKEN',
'Accept: application/json',
],
]);
$response = curl_exec($ch);
curl_close($ch);
// 204 No Contentimport requests
response = requests.delete(
"https://your-domain.com/api/v1/tags/15",
headers={
"Authorization": "Bearer YOUR_API_TOKEN",
"Accept": "application/json"
}
)
# 204 No ContentReturns 204 No Content on success.
Was this article helpful?