Tag API Methods

This page presents the main API methods for working with file category tags in the Brainysoft system: creating, retrieving, updating, deleting tags, changing order, publishing and unpublishing, as well as retrieving tag statistics.

API Methods for Working with File Category Tags

Method	URL	Description
GET\|HEAD	`api/tags`	Get list of tags
POST	`api/tags`	Create a new tag
PUT\|PATCH	`api/tags/{tag}`	Update tag (title)
GET\|HEAD	`api/tags/{tag}`	Get tag information
DELETE	`api/tags/{tag}`	Delete tag
PUT	`api/tags/{tag}/changeOrder`	Change tag order
PUT	`api/tags/{tag}/publish`	Publish tag
PUT	`api/tags/{tag}/unpublish`	Unpublish tag
GET	`api/statistics/tags`	Get tag statistics

Get List of Tags

GET /api/tags

Description

The method returns a list of all available file category tags with their attributes: name, alias, status, hierarchy.

Request Example

GET /api/tags

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750164920000, // Response time (UNIX timestamp, ms)
  "data": [
    {
      "id": 1, // Unique tag identifier
      "title": "Фотографии", // Tag name (displayed to user)
      "alias": "fotografii", // Technical tag name (can be used in URL/API)
      "status": "PUBLISHED", // Tag status
      "parentId": 0, // Parent tag ID (0 — if top-level tag)
      "level": 1 // Nesting level (e.g., 1 — root tag)
    }
  ]
}

Create a New Tag

POST /api/tags

Description

The method allows creating a new tag in the system. The request body contains the parameters of the new tag, such as name, alias, status, parent tag, and nesting level.

Request Example

POST /api/tags

json

{
  "id": 46, // Unique tag identifier
  "title": "Документы для займа", // Tag name (displayed to user)
  "alias": "loan_documents", // Technical tag name (can be used in URL/API)
  "status": "PUBLISHED", // Tag status
  "parentId": 0, // Parent tag ID (0 — if top-level tag)
  "level": 1 // Nesting level (e.g., 1 — root tag)
}

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750682383000, // Response time (UNIX timestamp, ms)
  "data": {
    "result": "ok", // Operation result
    "tag": 46 // Unique identifier of the created tag
  }
}

Update Tag (title)

PUT|PATCH /api/tags/{tag}

Description

The method allows changing only the name (title) of an existing tag by its identifier. Other fields (alias, status, parentId, level) cannot be changed with this method — they remain unchanged, alias will be automatically generated by the system based on the new title.

Request Parameters

{tag} (integer, required) — unique tag identifier.

Request Example

PUT|PATCH /api/tags/47

json

{
  "title": "Четвертый документ для займа" // New tag name
}

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750683228000, // Response time (UNIX timestamp, ms)
  "data": {
    "id": 47, // Unique tag identifier
    "title": "Четвертый документ для займа", // Tag name (displayed to user)
    "alias": "chetvertyiy-dokument-dlya-zayma", // Technical tag name (automatically generated)
    "status": "PUBLISHED", // Tag status
    "parentId": null, // Parent tag ID (null — if top-level tag)
    "level": 0 // Nesting level
  }
}

Get Tag Information

GET /api/tags/{tag}

Description

The method returns detailed information about a specific tag by its identifier. It is used to retrieve tag properties, its status, hierarchy, and other characteristics.

Request Parameters

{tag} (integer, required) — unique tag identifier.

Request Example

GET /api/tags/4

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750681352000, // Response time (UNIX timestamp, ms)
  "data": {
    "id": 4, // Unique tag identifier
    "title": "Документы заемщика", // Tag name (displayed to user)
    "alias": "dokumentyi-zaemschika", // Technical tag name (can be used in URL/API)
    "status": "PUBLISHED", // Tag status
    "parentId": 0, // Parent tag ID (0 — if top-level tag)
    "level": 1 // Nesting level (e.g., 1 — root tag)
  }
}

Delete Tag

DELETE /api/tags/{tag}

Description

The method allows deleting a tag by its identifier.

Request Parameters

{tag} (integer, required) — unique tag identifier.

Request Example

DELETE /api/tags/48

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750683985000, // Response time (UNIX timestamp, ms)
  "data": {
    "status": "deleted" // Tag deletion status
  }
}

Change Tag Order

PUT /api/tags/{tag}/changeOrder

Description

The method allows changing the order (position) of a tag relative to another tag in the list. To do this, specify the identifier of the neighboring tag and the desired position relative to it.

Request Parameters

{tag} (integer, required) — unique identifier of the tag whose order is being changed.

Request Body (application/json)

Field	Type	Description
neighborTagId	integer	Identifier of the neighboring tag relative to which the order will be changed
position	string	Position relative to the neighboring tag. Possible values: "before" — before the specified tag, "after" — after the specified tag

Request Example

PUT /api/tags/47/changeOrder

json

{
  "neighborTagId": 46, // Neighboring tag identifier
  "position": "after" // Position relative to the neighboring tag
}

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750833694000, // Response time (UNIX timestamp, ms)
  "data": {
    "result": "ok", // Operation result
    "tag": 47, // Unique tag identifier
    "currentOrder": "0 46" // Current tag order
  }
}

Publish and Unpublish Tag

PUT /api/tags/{tag}/publish - Publish tag

PUT /api/tags/{tag}/unpublish - Unpublish tag

Description

publish - the method changes the tag status to "published", making it available for use in the system.

unpublish - the method changes the tag status to "unpublished", making it unavailable for use in the system.

Request Parameters

{tag} (integer, required) — unique tag identifier.

Request Example

PUT /api/tags/47/unpublish

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750684897000, // Response time (UNIX timestamp, ms)
  "data": {
    "id": 47, // Unique tag identifier
    "title": "Четвертый документ для займа", // Tag name (displayed to user)
    "alias": "chetvertyiy-dokument-dlya-zayma", // Technical tag name (can be used in URL/API)
    "status": "UNPUBLISHED", // Tag status
    "parentId": null, // Parent tag ID (null — if top-level tag)
    "level": 0 // Nesting level
  }
}

Get Tag Statistics

GET /api/statistics/tags

Description

The method returns statistics for all file category tags, including the number of files with each tag.

Request Example

GET /api/statistics/tags

Successful Response Example

json

{
  "status": "ok", // Request execution status
  "timestamp": 1750164401000, // Response time (UNIX timestamp, ms)
  "data": {
    "tags": [
      {
        "id": 1, // Unique tag identifier
        "alias": "fotografii", // Technical tag name (can be used in URL/API)
        "label": "Фотографии", // Tag name (synonym of title field, used in statistics)
        "files": 0, // Number of current files with this tag
        "deleted": 0, // Number of deleted files with this tag
        "all": 0 // Total number of files with this tag
      }
    ]
  }
}

Field Descriptions

Field	Type	Description
status	string	Request execution status
timestamp	integer	Response time (UNIX timestamp, ms)
data	object/array	Main response data
id	integer	Unique tag identifier
title	string	Tag name (displayed to user)
alias	string	Technical tag name (can be used in URL/API)
status	string	Tag status (`PUBLISHED`, `UNPUBLISHED`, `DRAFT`, etc.)
parentId	integer	Parent tag ID (0 or null — if top-level tag)
level	integer	Nesting level (e.g., 1 — root tag)
label	string	Tag name (synonym of title field, used in statistics)
files	integer	Number of current files with this tag
deleted	integer	Number of deleted files with this tag
all	integer	Total number of files with this tag
result	string	Operation result
tag	integer	Unique tag identifier
currentOrder	string	Current tag order
neighborTagId	integer	Neighboring tag identifier
position	string	Position relative to the neighboring tag

Tag API Methods ​

API Methods for Working with File Category Tags ​

Get List of Tags ​

Create a New Tag ​

Update Tag (title) ​

Get Tag Information ​

Delete Tag ​

Change Tag Order ​

Publish and Unpublish Tag ​

Get Tag Statistics ​

Field Descriptions ​

Tag API Methods

API Methods for Working with File Category Tags

Get List of Tags

Create a New Tag

Update Tag (title)

Get Tag Information

Delete Tag

Change Tag Order

Publish and Unpublish Tag

Get Tag Statistics

Field Descriptions