Tags API Overview

The Informer Tags API provides endpoints for creating and managing tags to categorize and filter content. Tags can be applied to reports, datasets, datasources, jobs, queries, templates, assistants, and libraries. All routes are prefixed with /api.

Features

• Flexible Tagging - Tag multiple entity types
• Color Coding - Assign colors to tags for visual organization
• Bulk Operations - Add/remove tags from multiple entities at once
• Bulk Updates - Create, update, and delete tags in batches
• Search - Find tags by name

Authentication

All Tag API endpoints require authentication via session cookies or API tokens. Creating tags requires permission.tags.create.

Endpoints

GET /api/tags

Get a list of all tags with optional name search.

Authentication: Required (session)

Query Parameters:

Parameter	Type	Description
name	string	Filter tags by name (partial match)

Response:

{
  "_links": {
    "self": { "href": "/api/tags" }
  },
  "_embedded": {
    "inf:tag": [
      {
        "id": "tag-123",
        "name": "high-priority",
        "color": "#FF5722",
        "createdAt": "2024-01-15T10:30:00Z",
        "updatedAt": "2024-01-15T10:30:00Z",
        "_links": {
          "self": { "href": "/api/tags/tag-123" }
        }
      },
      {
        "id": "tag-456",
        "name": "sales",
        "color": "#4CAF50",
        "createdAt": "2024-01-14T14:22:00Z",
        "updatedAt": "2024-01-14T14:22:00Z",
        "_links": {
          "self": { "href": "/api/tags/tag-456" }
        }
      }
    ]
  },
  "start": 0,
  "count": 2,
  "total": 2
}

---

POST /api/tags

Create a new tag.

Authentication: Required (session)

Pre-blocks: permission.tags.create(auth)

Request Body:

Field	Type	Required	Description
name	string	Yes	Tag name
color	string	No	Hex color code (e.g., #FF5722) - empty string allowed

Example Request:

{
  "name": "urgent",
  "color": "#F44336"
}

Response:

Returns the created tag object with 201 Created status and Location header.

{
  "id": "tag-789",
  "name": "urgent",
  "color": "#F44336",
  "createdAt": "2024-01-15T14:22:00Z",
  "updatedAt": "2024-01-15T14:22:00Z",
  "_links": {
    "self": { "href": "/api/tags/tag-789" }
  }
}

---

GET /api/tags/{id}

Get a specific tag by ID.

Authentication: Required (session)

Response:

{
  "id": "tag-123",
  "name": "high-priority",
  "color": "#FF5722",
  "parentId": null,
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z",
  "_links": {
    "self": { "href": "/api/tags/tag-123" },
    "inf:permissions": { "href": "/api/tags/tag-123/permissions" }
  }
}

---

PUT /api/tags/{id}

Update a tag's name or color.

Authentication: Required (session)

Pre-blocks: permission.tag.edit(params.id)

Request Body:

Field	Type	Description
name	string	New tag name
color	string	New hex color code

Example Request:

{
  "name": "critical",
  "color": "#D32F2F"
}

Response:

Returns the updated tag object.

---

DELETE /api/tags/{id}

Delete a tag and remove it from all entities.

Authentication: Required (session)

Pre-blocks: permission.tag.delete(params.id)

Response:

Returns 204 No Content on successful deletion.

Side Effects:

• Removes tag associations from all entities
• Cannot be undone

---

GET /api/tags/{id}/permissions

Get permissions for a tag.

Authentication: Required (session)

Response:

Returns tag permissions object.

---

POST /api/tags/_bulk-assign

Add or remove tags from multiple entities.

Authentication: Required (session)

Request Body:

Field	Type	Required	Description
entities	array	Yes	Array of entity IDs (UUIDs) to tag
addTags	array	No	Array of tag IDs to add (default: [])
removeTags	array	No	Array of tag IDs to remove (default: [])

Example Request:

{
  "entities": [
    "report-123",
    "dataset-456",
    "job-789"
  ],
  "addTags": [
    "tag-urgent",
    "tag-sales"
  ],
  "removeTags": [
    "tag-draft"
  ]
}

Response:

Returns 200 OK on success.

Permission Checks:

• User must have {entity}:assignTags permission on each entity
• Entities without permission are silently skipped
• Supports: reports, datasets, datasources, jobs, queries, templates, assistants, libraries

Process:

1. Look up all entities and check permissions
2. Remove specified tags from permitted entities
3. Add specified tags to permitted entities

---

POST /api/tags/_bulk-update

Bulk add, update, and remove tags in a single transaction.

Authentication: Required (session)

Pre-blocks: permission.tags.create

Request Body:

Field	Type	Description
add	array	Tags to create
remove	array	Tag IDs to delete
update	array	Tags to update

Add Array Items:

Field	Type	Description
id	string	Tag ID (client-generated UUID)
name	string	Tag name
color	string	Hex color code

Update Array Items:

Field	Type	Description
id	string	Tag ID (UUID)
name	string	New tag name
color	string	New hex color code

Example Request:

{
  "add": [
    {
      "id": "new-tag-1",
      "name": "archived",
      "color": "#9E9E9E"
    }
  ],
  "remove": [
    "old-tag-123"
  ],
  "update": [
    {
      "id": "tag-456",
      "name": "active",
      "color": "#4CAF50"
    }
  ]
}

Response:

Returns success (no content).

Processing Order:

1. Remove tags (and their associations)
2. Add new tags
3. Update existing tags

---

Supported Entity Types

Tags can be applied to:

• Reports - Report definitions
• Datasets - Dataset configurations
• Datasources - Data source connections
• Jobs - Scheduled jobs
• Queries - Saved queries
• Templates - Document templates
• Assistants - AI assistants
• Libraries - Document libraries

Use Cases

Status Tags

- draft (#FFC107)
- review (#FF9800)
- approved (#4CAF50)
- archived (#9E9E9E)

Priority Tags

- critical (#F44336)
- high (#FF5722)
- medium (#FF9800)
- low (#FFC107)

Department Tags

- sales (#2196F3)
- marketing (#9C27B0)
- engineering (#00BCD4)
- finance (#4CAF50)

Color Recommendations

Use hex color codes for visual consistency:

• Red: #F44336 (critical, error)
• Orange: #FF9800 (warning, review)
• Yellow: #FFC107 (draft, pending)
• Green: #4CAF50 (approved, success)
• Blue: #2196F3 (info, sales)
• Purple: #9C27B0 (marketing)
• Grey: #9E9E9E (archived, inactive)