Tags

Organize and categorize reports using tags.

Overview

Tags provide a flexible way to categorize and organize reports. Multiple tags can be applied to a single report, and tags can be used for filtering and search.

GET /api/reports/{id}/tags

Get all tags associated with a report.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID

Response:

{
  "_links": {
    "self": { "href": "/api/reports/{id}/tags" }
  },
  "_embedded": {
    "inf:tag-entity": [
      {
        "id": "uuid",
        "tagId": "sales",
        "reportId": "team:sales-dashboard",
        "_links": {
          "self": { "href": "/api/reports/team:sales-dashboard/tags/sales" },
          "inf:report": { "href": "/api/reports/team:sales-dashboard" },
          "inf:tag": { "href": "/api/tags/sales" }
        },
        "_embedded": {
          "inf:tag": {
            "id": "sales",
            "name": "Sales",
            "color": "#4CAF50",
            "_links": {
              "self": { "href": "/api/tags/sales" }
            }
          }
        }
      }
    ]
  },
  "start": 0,
  "count": 1,
  "total": 1
}

Response Fields:

Field	Type	Description
id	string	Tag entity UUID
tagId	string	Tag identifier
reportId	string	Report ID

The embedded inf:tag contains full tag metadata including name and color.

---

GET /api/reports/{id}/tags/{tagId}

Get a specific tag association.

Authentication: Required

Path Parameters:

Parameter	Type	Description
id	string	Report ID
tagId	string	Tag ID

Response:

{
  "id": "uuid",
  "tagId": "sales",
  "reportId": "team:sales-dashboard",
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard/tags/sales" },
    "inf:report": { "href": "/api/reports/team:sales-dashboard" },
    "inf:tag": { "href": "/api/tags/sales" }
  }
}

---

PUT /api/reports/{id}/tags/{tagId}

Add a tag to a report.

Authentication: Required

Permissions: report:assignTags

Path Parameters:

Parameter	Type	Description
id	string	Report ID
tagId	string	Tag ID to add

Request Body:

Empty body or {}

Response:

{
  "id": "uuid",
  "tagId": "sales",
  "reportId": "team:sales-dashboard",
  "_links": {
    "self": { "href": "/api/reports/team:sales-dashboard/tags/sales" }
  }
}

Status Code: 200 OK (if already exists) or 201 Created (new association)

Behavior:

• Creates a tag association if it doesn't exist
• Idempotent - safe to call multiple times
• The tag must already exist (see Tag API for creating tags)
• Executes in a database transaction

Use Case:

Associate an existing tag with a report for categorization.

---

DELETE /api/reports/{id}/tags/{tagId}

Remove a tag from a report.

Authentication: Required

Permissions: report:assignTags

Path Parameters:

Parameter	Type	Description
id	string	Report ID
tagId	string	Tag ID to remove

Response:

204 No Content on success.

Behavior:

• Removes the tag association
• Does not delete the tag itself (only removes from this report)
• Executes in a database transaction

Use Case:

Remove a tag categorization from a report.

---

Tag Management Workflow

1. List available tags

GET /api/tags

2. Apply tag to report

PUT /api/reports/team:sales-dashboard/tags/sales

3. View report's tags

GET /api/reports/team:sales-dashboard/tags

4. Remove tag

DELETE /api/reports/team:sales-dashboard/tags/sales

---

Tag Best Practices

Use tags for:

• Department/team categorization (sales, marketing, finance)
• Report type classification (dashboard, analysis, summary)
• Data domain (customer, product, revenue)
• Update frequency (daily, weekly, monthly)
• Status labels (draft, published, archived)

Tag naming:

• Use lowercase with hyphens for multi-word tags
• Keep tag IDs short and meaningful
• Use consistent naming conventions across the organization

Example tag structure:

dept:sales
dept:marketing
type:dashboard
type:analysis
freq:daily
freq:weekly
domain:customer
domain:product

---

Related Endpoints

• GET /api/tags - List all available tags
• POST /api/tags - Create a new tag
• GET /api/tags/{id} - Get tag details
• PUT /api/tags/{id} - Update tag properties
• DELETE /api/tags/{id} - Delete a tag

See the Tag API documentation for full tag management capabilities.