Dashboard Tags

Dashboard tags are machine-readable classification metadata. Use them to find and organize dashboards and Data Apps that a user is already allowed to access, such as building separate product areas for operations and inbound ticketing.

product:operations-agent
product:inbound-ticketing
audience:operations

Tags are not permissions, folders, display names, publication state, or part of the rendered dashboard. A tag filter can only narrow the caller's existing authorized dashboard set. It cannot grant access or reveal dashboards from another tenant.

Choose Stable Tag Values

A tag is an opaque lowercase ASCII value made from letters, numbers, and hyphenated segments. Colons can separate a namespace from its value.

Valid: product:inbound-ticketing, audience:operations, release:2026-q3
Invalid: Product:Inbound, product_inbound, product:inbound
Maximum length: 64 characters per tag
Maximum set size: 20 unique tags per dashboard or filter

Semaphor rejects invalid, duplicate, or excessive values. It does not trim, lowercase, deduplicate, slugify, or otherwise rewrite them. Returned tag arrays are sorted in ascending lexical order. An untagged dashboard returns tags: [].

Raw tags can appear as technical chips in the Semaphor console. For a polished customer-facing navigation, map stable tag values to your own display copy:

Tag selector	Customer-facing copy
`product:operations-agent`	Operations Agent
`product:inbound-ticketing`	Inbound Ticketing

Do not put secrets, credentials, personal data, or sensitive tenant information in tags.

Assign Tags in the Console

The project dashboard table includes a default-visible Tags column. Each row shows up to two tag chips and a +N overflow control. You can hide the Tags column without changing which dashboards are loaded.

Select a tag chip to filter the dashboards already loaded in the active organization or tenant view.
The tag filter is exact and combines with the existing title filter.
Remove the visible Filtered by chip to clear the tag filter.
Open the row's actions menu and choose Edit tags to replace or clear that dashboard's complete tag set.

The editor suggests tags used by dashboards already loaded in the current view. These suggestions are a convenience, not a global tag registry. The server authorizes the replacement when you save, so opening the editor does not prove that you have edit access.

Console filtering is client-side over the active loaded view. It does not search dashboards outside that view, add server-side pagination, provide bulk assignment, or enumerate a project-wide tag catalog.

Create or Replace Tags with the API

The Management API accepts optional tags when creating a dashboard:

curl --request POST \
  --url "$SEMAPHOR_URL/api/management/v1/dashboards" \
  --header "Authorization: Bearer $SEMAPHOR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "title": "Inbound Operations",
    "tags": ["audience:operations", "product:inbound-ticketing"]
  }'

To edit an existing dashboard or Data App, PATCH uses full replacement semantics:

Omit tags to preserve the current set.
Send "tags": [] to clear all tags.
Send a non-empty array to replace the complete set.

curl --request PATCH \
  --url "$SEMAPHOR_URL/api/management/v1/dashboards/$DASHBOARD_ID" \
  --header "Authorization: Bearer $SEMAPHOR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "tags": ["audience:operations", "product:operations-agent"]
  }'

To clear the set, send the same request with an empty array:

{ "tags": [] }

To preserve tags while changing another field, omit tags from that PATCH request.

Tag mutation uses the dashboard's existing edit permission. A tag-only request that sends the same set is a no-op and does not advance updatedAt. Changed tags use the normal dashboard update timestamp, but tags do not enter the dashboard template or Git history and do not require a commit message.

Management dashboard creation remains dashboard-only. Existing Data Apps can be tagged through PATCH.

Filter Dashboards Programmatically

Use repeated singular tag parameters for exact matching:

curl --get \
  --url "$SEMAPHOR_URL/api/management/v1/dashboards" \
  --header "Authorization: Bearer $SEMAPHOR_TOKEN" \
  --data-urlencode "tag=product:inbound-ticketing"

When more than one tag is supplied:

Omit tagMatch, or use tagMatch=all, to require every requested tag.
Use tagMatch=any to require at least one requested tag.

This default-all request requires both tags:

curl --get \
  --url "$SEMAPHOR_URL/api/management/v1/dashboards" \
  --header "Authorization: Bearer $SEMAPHOR_TOKEN" \
  --data-urlencode "tag=product:inbound-ticketing" \
  --data-urlencode "tag=audience:operations"

curl --get \
  --url "$SEMAPHOR_URL/api/management/v1/dashboards" \
  --header "Authorization: Bearer $SEMAPHOR_TOKEN" \
  --data-urlencode "tag=product:inbound-ticketing" \
  --data-urlencode "tag=product:operations-agent" \
  --data-urlencode "tagMatch=any" \
  --data-urlencode "kind=dashboard" \
  --data-urlencode "limit=100" \
  --data-urlencode "offset=0"

kind=dashboard and kind=data_app are optional exact filters. The search parameter remains case-insensitive title and description search; it does not search tags. Tag, kind, and search filters combine with the caller's existing authorization.

The signed project access token establishes project scope. Do not send projectId or tenantId to the Management dashboard list. Pagination defaults to limit=500 and offset=0, and total is the count after authorization and all filters.

For example, this requests the second 50-result page of Data Apps whose title or description contains operations:

curl --get \
  --url "$SEMAPHOR_URL/api/management/v1/dashboards" \
  --header "Authorization: Bearer $SEMAPHOR_TOKEN" \
  --data-urlencode "kind=data_app" \
  --data-urlencode "search=operations" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=50"

Use the response total to determine whether another offset page exists.

Lifecycle Behavior

Existing records and ordinary Management create requests that omit optional tags start with an empty tag set. Semaphor does not infer, prefill, or backfill tags.
Duplicating a dashboard copies its tags and existing visibility. The duplicate operation does not accept a tag override.
Migrating to a new target copies the source tags and creates a non-public target.
Replacing an existing migration target preserves that target's tags.
Deleting a dashboard removes its tags with the dashboard record.

API Reference

Current Scope

Dashboard tags intentionally do not include a global registry, descriptions, colors, aliases, localization, facets, global rename, bulk assignment, fuzzy matching, MCP tag mutation, or a tag-specific permission model. Use stable values you control and maintain the customer-facing presentation in your application.