/api/v1/tags

Manages the complete set of tag groups and tags. GET returns every taggroup and its tags and requires only an authenticated user; POST replaces the entire set from the request body, deleting any group or tag absent from it, writes the taggroup and tag tables directly in the request transaction (effective immediately, no working copy or commit step), and requires the system.tagmanager system right.

GET /tags — Get all tags

Get all tags

get

This endpoint returns all available taggroups and tags.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Responses

200

Success

application/json

_basetypestring · enumOptional

Always taggroup.

Possible values:

401

No authenticated user. The request must carry a valid access token.

Differs from easydb 5: a missing/invalid session is reported as 401 (UserRequired); easydb 5 documents the unauthenticated case on this endpoint as a 400 ("Not Authenticated").

application/json

[
  {
    "_basetype": "taggroup",
    "_tags": [
      {
        "_id": 1,
        "displayname": {
          "de-DE": "Dogs"
        },
        "enabled": true,
        "displaytype": "detail",
        "sticky": true
      }
    ],
    "taggroup": {
      "_id": 1,
      "displayname": {
        "de-DE": "Deutscher text",
        "en-US": "English text"
      },
      "reference": "text",
      "shortname": "text",
      "type": "checkbox"
    }
  }
]

POST /tags — Create, update or delete taggroups and tags

Create, update or delete taggroups and tags

post

Replaces the entire set of tag groups and tags. The request body is the complete desired list: groups and tags present are created or updated; any group or tag currently in the database but absent from the request is deleted. The change is written directly to the taggroup and tag tables in the request transaction and is effective immediately; there is no working copy and no separate commit step. Deletions of still-referenced tags either return a 202 (auto-removable contexts, confirm with delete_policy=remove_tags) or a 400 TagsInUse (must be resolved manually first). Changing a tag's _acl re-validates affected collection objects; if that re-validation exceeds the time limit a 202 is returned offering to run it in the background (confirm with background_invalid_acl=true). Requires the system.tagmanager system right. Rejected with 400 ReadOnlyMode while the server is in read-only mode.

Differs from easydb 5: deleting a still-referenced tag is confirmed with delete_policy=remove_tags (auto-removable contexts) or rejected with 400 TagsInUse (manual-resolution contexts), and the collection-ACL re-validation is confirmed with background_invalid_acl. easydb 5 documents neither a delete_policy nor a TagsInUse error; its only documented confirmation parameter for this save is collection_rights_policy.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

Access token in the Authorization header: Authorization: Bearer <token>.

Query parameters

delete_policystring · enumOptional

Confirmation flag for deleting tags that are still referenced only in contexts where fylr can clean them up automatically (collection.create_object, objecttype_tag, pool_tag). The only recognized value is remove_tags. Without it, such a deletion returns 202 asking for confirmation; resend the identical request with delete_policy=remove_tags to proceed (the tag is removed from those contexts and deleted). It has no effect on tags referenced in manual-resolution contexts (records, ACLs, column/mask filters, workflows, right presets, baseconfig), which always return 400 TagsInUse.

Possible values:

background_invalid_aclbooleanOptional

Confirmation flag for the collection re-validation that runs when a tag's _acl changes. If the synchronous re-validation of the affected collection objects exceeds the time limit, the request returns a 202 asking for confirmation; resend the identical request with background_invalid_acl=true to apply the change immediately and schedule the re-validation as a background index job instead.

background_invalid_acl_timelimitstringOptional

Overrides the time limit for the synchronous collection re-validation (a Go duration string such as 30s). When the limit is exceeded a 202 is returned; see background_invalid_acl.

Bodyobject[]

application/json

_basetypestring · enumOptional

Always taggroup.

Possible values:

Responses

200

Success

No content

202

Request must be resent and confirmed. Two situations produce this response:

• One or more tags that would be deleted are still referenced in places where they can be cleaned up automatically (collection.create_object, objecttype_tag, pool_tag), but an explicit confirmation is required. Resend the identical request with the query parameter delete_policy=remove_tags to confirm.
• A changed tag _acl triggered collection re-validation that exceeded the time limit. Resend the identical request with background_invalid_acl=true to apply the change and run the re-validation in the background.

The tasks[].buttons[].name/value of the returned payload name the query parameter to resend with.

application/json

400

The request could not be processed. The code field identifies which validation rejected the request. Codes include TagsInUse (a tag to be deleted is still referenced in a manual-resolution context), ReadOnlyMode (server in read-only mode), the rights-validation codes raised while checking each tag's _acl (UnknownRight, UnknownRightParam, UnknownRightValue, ChoiceNotUnique, …), and ServerGeneric for a malformed body or an unknown taggroup type (only checkbox and choice are accepted).

application/json

401

No authenticated user. The request must carry a valid access token.

Differs from easydb 5: a missing/invalid session is reported as 401 (UserRequired); easydb 5 documents the unauthenticated case on this endpoint as a 400 ("Not Authenticated").

application/json

403

The authenticated user lacks the system.tagmanager system right (and is not system.root). Error code is SystemRightRequired.

Differs from easydb 5: a missing system right is reported as 403 (SystemRightRequired); easydb 5 documents the missing-right case on this endpoint as a 400 ("No System Right").

application/json

No content