/api/v1/transitions

Manage workflow transitions — rules that fire when objects are inserted, updated or deleted, gated on the object's tags, and run actions (set/unset tags, send email, call a webhook, change the owner, or invoke a plugin callback). This endpoint is the admin surface: list the defined transitions, replace them. The transitions themselves are evaluated implicitly during the object save pipeline, not through a separate endpoint.

Both operations require the system.tagmanager system right (a user holding system.root is always granted it). The endpoint takes no path, query, or header parameters; authentication uses the standard access token (see the API overview).

Differs from easydb 5: easydb 5 gated only the POST, and on the system.rights_management right; fylr gates both methods on system.tagmanager. easydb 5 returned 400 when the session was unauthenticated or lacked the right; fylr returns 401 (UserRequired) and 403 (SystemRightRequired) respectively.

GET /transitions — List all defined transitions.

List all defined transitions.

get

Returns the global workflow transitions (those not bound to a specific pool or objecttype), ordered by their position. Pool- and objecttype-scoped transitions are excluded; read those through the corresponding pool / objecttype endpoints.

Requires the system.tagmanager system right.

Differs from easydb 5: easydb 5's GET needed only an authenticated session; fylr also requires system.tagmanager.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

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

Responses

200

Array of transition descriptors.

application/json

A workflow transition descriptor — one rule in the admin-managed transition set. GET / POST /api/v1/transitions read and replace this set; the rules themselves fire implicitly through the object pipeline (insert / update / delete / tag), not via a separate call.

_idinteger · int64Optional

Server-issued numeric id.

typestring · enumRequired

Transition kind. One of resolve, reject, exit_resolve, exit_reject, process. Any other value is rejected with a ServerGeneric error (HTTP 400).

Possible values:

commentstringOptional

Admin-facing comment / note (not user-visible).

Differs from easydb 5: this field does not exist in easydb 5; it is a fylr addition.

stickybooleanOptional

Boolean flag stored on the transition and round-tripped verbatim by this endpoint.

who_notbooleanOptional

If true, the who list is interpreted as a deny-list instead of an allow-list — every user EXCEPT those in who can invoke the transition.

Differs from easydb 5: this field does not exist in easydb 5; it is a fylr addition.

objecttype_idsinteger · int64[]Optional

Object types the transition applies to. Empty means it applies to every object type.

401

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

application/json

403

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

application/json

[
  {
    "_id": 1,
    "objecttype_ids": [
      1
    ]
  },
  {
    "_id": 2,
    "objecttype_ids": []
  }
]

POST /transitions — Replace the full set of transitions.

Replace the full set of transitions.

post

Accepts an array of transition descriptors and replaces the global transition set with them (entries with _id are updated; entries without _id are created; transitions that exist on the server but not in the payload are deleted). A partial array therefore removes every omitted global transition. Transitions scoped to a specific pool or objecttype are not managed here — they are sent through the corresponding pool / objecttype endpoints.

Requires the system.tagmanager system right. Rejected if the instance is in read-only mode (checked before the right, so a read-only instance returns 400 ReadOnlyMode even to a user without the right).

The response echoes the persisted set, with server-issued _ids filled in. On success a X-Fylr-Cache-ID response header carries the new cache id (format <startup-unix>-<cache-id>), bumped after the transaction commits.

Differs from easydb 5: fylr gates this on system.tagmanager (easydb 5 used system.rights_management); validation failures and the read-only rejection surface as 400 with explicit error codes (ServerGeneric, ReadOnlyMode) rather than easydb 5's bare 400.

Authorizations

BearerAuthAccessTokenQueryFylrAuthHeader

AuthorizationstringRequired

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

Bodyobject[]

application/json

A workflow transition descriptor — one rule in the admin-managed transition set. GET / POST /api/v1/transitions read and replace this set; the rules themselves fire implicitly through the object pipeline (insert / update / delete / tag), not via a separate call.

_idinteger · int64Optional

Server-issued numeric id.

typestring · enumRequired

Transition kind. One of resolve, reject, exit_resolve, exit_reject, process. Any other value is rejected with a ServerGeneric error (HTTP 400).

Possible values:

commentstringOptional

Admin-facing comment / note (not user-visible).

Differs from easydb 5: this field does not exist in easydb 5; it is a fylr addition.

stickybooleanOptional

Boolean flag stored on the transition and round-tripped verbatim by this endpoint.

who_notbooleanOptional

If true, the who list is interpreted as a deny-list instead of an allow-list — every user EXCEPT those in who can invoke the transition.

Differs from easydb 5: this field does not exist in easydb 5; it is a fylr addition.

objecttype_idsinteger · int64[]Optional

Object types the transition applies to. Empty means it applies to every object type.

Responses

200

The persisted transition set, in the same shape as GET /transitions. Newly-created entries (sent without _id) come back with their server-issued _id. The order matches the order sent in the request body.

application/json

A workflow transition descriptor — one rule in the admin-managed transition set. GET / POST /api/v1/transitions read and replace this set; the rules themselves fire implicitly through the object pipeline (insert / update / delete / tag), not via a separate call.

_idinteger · int64Optional

Server-issued numeric id.

typestring · enumRequired

Transition kind. One of resolve, reject, exit_resolve, exit_reject, process. Any other value is rejected with a ServerGeneric error (HTTP 400).

Possible values:

commentstringOptional

Admin-facing comment / note (not user-visible).

Differs from easydb 5: this field does not exist in easydb 5; it is a fylr addition.

stickybooleanOptional

Boolean flag stored on the transition and round-tripped verbatim by this endpoint.

who_notbooleanOptional

If true, the who list is interpreted as a deny-list instead of an allow-list — every user EXCEPT those in who can invoke the transition.

Differs from easydb 5: this field does not exist in easydb 5; it is a fylr addition.

objecttype_idsinteger · int64[]Optional

Object types the transition applies to. Empty means it applies to every object type.

400

Read-only mode is enabled (code ReadOnlyMode, checked before the right and before parsing), or the payload is invalid (code ServerGeneric). ServerGeneric covers: unparseable JSON; an entry whose _id matches no existing transition in the database; an unknown transition type (not one of resolve, reject, exit_resolve, exit_reject, process); an unknown operations value (not INSERT / UPDATE / DELETE); a tagfilter:before / tagfilter:after that lists the same tag id more than once; a who entry whose _basetype is neither user nor group, or that mixes the wrong key for its basetype; a webhook action with an unknown callback (not pre_save / after_commit_async) or a name not declared in the base config; or an action type that matches no built-in (email, set_tags, webhook, change_owner) and resolves to no registered plugin callback.

application/json

401

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

application/json

403

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

application/json

[
  {
    "type": "process",
    "operations": [
      "INSERT",
      "UPDATE"
    ],
    "sticky": false,
    "objecttype_ids": [
      1
    ],
    "actions": [
      {
        "type": "set_tags",
        "info": {
          "tags": [
            {
              "_id": 5,
              "set": true
            }
          ]
        }
      }
    ],
    "who": [
      {
        "_basetype": "user",
        "user": {
          "_id": 1
        }
      }
    ]
  }
]