Tags

Create and manage color-coded tags, then assign them to projects for filtering and organization.

Tags are organization-scoped labels with a name and a color. Assign them to projects to group and filter resources across your organization.

Creating a tag

Tags require a name (1–64 characters, unique within the organization). Color is optional and must be a hex string in #rrggbb or #rrggbbaa format.

POST /api/trpc/tag.create
Content-Type: application/json

{
  "name": "production",
  "color": "#ef4444"
}

Requires the services.create permission. Tag names must be unique per organization — attempting to reuse a name returns a CONFLICT error.

The audit log records every create action on the tag resource type.

Listing tags

Returns all tags for the active organization, sorted alphabetically by name.

GET /api/trpc/tag.all

Both tag and dashboard are mounted in the REST/OpenAPI root, so tag.one is reachable with a flat path and an API token — unlike the /api/trpc/... calls above, this form takes plain query params, no input= JSON wrapping:

curl -X 'GET' \
  'https://your-domain/api/tag.one?tagId=<tag-id>' \
  -H 'accept: application/json' \
  -H 'x-api-key: <token>'

Returns NOT_FOUND if the tag does not belong to the active organization.

Updating a tag

Both name and color are optional — pass only the fields you want to change.

POST /api/trpc/tag.update
Content-Type: application/json

{
  "tagId": "<tag-id>",
  "name": "staging",
  "color": "#f59e0b"
}

Requires the services.update permission. Renaming to a name already in use returns CONFLICT.

Removing a tag

POST /api/trpc/tag.remove
Content-Type: application/json

{
  "tagId": "<tag-id>"
}

Requires the services.delete permission.

Removing a tag also removes it from all projects it was assigned to.

Assigning a tag to a project

POST /api/trpc/tag.assignToProject
Content-Type: application/json

{
  "projectId": "<project-id>",
  "tagId": "<tag-id>"
}

Both the project and the tag must belong to the active organization. Members with a custom role must have the project listed in their accessedProjects grant; owners and admins have unrestricted access.

Assigning the same tag twice returns CONFLICT.

Removing a tag from a project

POST /api/trpc/tag.removeFromProject
Content-Type: application/json

{
  "projectId": "<project-id>",
  "tagId": "<tag-id>"
}

Same access requirements as assignToProject.

Bulk-replacing project tags

Replaces the full tag set for a project in a single transaction — removes all existing associations, then inserts the new list.

POST /api/trpc/tag.bulkAssign
Content-Type: application/json

{
  "projectId": "<project-id>",
  "tagIds": ["<tag-id-1>", "<tag-id-2>"]
}

Pass an empty tagIds array to clear all tags from a project.

bulkAssign is not included in the OpenAPI schema because its array input is not supported by the tRPC OpenAPI generator.

Permissions summary

Operation	Required permission
Create tag	`services.create`
Update tag	`services.update`
Remove tag	`services.delete`
Assign / remove from project	Owner, Admin, or project in `accessedProjects`
List / get tags	Any authenticated member