SettingsMove one of my front-page widgets

Move one of my front-page widgets

Moves one of the caller's front-page widgets to a new (zero-based) position in the caller's own order.

Reads the caller's stored order (PersonalWidgetSettings on the FrontPage), renumbers it — widgets the caller's roles grant first, in their current order, then the others — moves the given widget to DisplayOrder + 1 and shifts the widgets in between by one, then saves the caller's order. Only the caller's own front page is affected. When the widget is not in the stored order, not granted, or the caller has no granted widgets, nothing is written and the response is still 204.

Use it to:

  • Persist a drag-and-drop reorder of the caller's front-page widgets

Not for:

  • Switching a widget on / off for the account → PUT /v2/features

Behaviour:

  • Idempotent.
  • Safe to retry.
  • Duplicates: Repeating the same move gives the same order.
  • Side effect: Rewrites the caller's FrontPage / PersonalWidgetSettings value: every stored widget is renumbered (granted widgets 1..n, then non-granted ones), so positions of widgets the caller no longer has also change.
  • Changes are visible to the next read immediately.

Call first: GET /v2/page-settings/widgets

Next: GET /v2/page-settings/widgets

See also: GET /v2/page-settings/{pageIdentifier}

curl -X PATCH "https://app3.timelog.com/your-account/api/v2/page-settings/widgets/displayorder" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
  "WidgetId": 123,
  "DisplayOrder": 42
}'
{}
PATCH
/v2/page-settings/widgets/displayorder
PATCH
Base URLstring

Target server for requests. Edit to use your own host.

Bearer Token
Bearer Tokenstring
Required

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.

OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp). The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user. > Not yet documented: how to obtain a token. > Not yet documented: token lifetime.
Content-Typestring
Required

The media type of the request body

Options: application/json
WidgetIdinteger
Required

The widget to move: its page id, as returned in UserWidgetRead.WidgetID. Refers to UserWidgetRead.WidgetID. Look up valid values with GET /v2/page-settings/widgets. - omitted, or not in the caller's stored widget order, or not granted by the caller's roles — Nothing is written; the call still returns 204. Valid values come from GET /v2/page-settings/widgets.

Format: int32
DisplayOrderinteger
Required

The new position, ZERO-based (0 = first). The server adds 1 and stores 1-based positions; the other widgets of the caller shift to make room, and the order is renumbered visible widgets first, then widgets the caller's roles no longer grant. - omitted — 0 — moves the widget to the first position. - negative or beyond the last position — Not validated; stored as given (+1). Sorting still works but positions are no longer 1..N.

Format: int32
Request Preview
Response

Response will appear here after sending the request

Authentication

header
Authorizationstring
Required

Bearer token. OAuth 2.0 bearer token, sent as Authorization: Bearer <token>. JWT and reference tokens are both accepted. The token must carry the required scope (default tlp).

The token's sub claim is the acting user. A token WITHOUT sub (client-credentials) acts as the system service user. If the sub user cannot log in (inactive, locked, deleted), the request is rejected with 401 — it is no longer let through without a user.

Not yet documented: how to obtain a token.

Not yet documented: token lifetime.

Body

application/json
WidgetIdinteger
Required

The widget to move: its page id, as returned in UserWidgetRead.WidgetID.

Refers to UserWidgetRead.WidgetID. Look up valid values with GET /v2/page-settings/widgets.

  • omitted, or not in the caller's stored widget order, or not granted by the caller's roles — Nothing is written; the call still returns 204.

Valid values come from GET /v2/page-settings/widgets.

DisplayOrderinteger
Required

The new position, ZERO-based (0 = first). The server adds 1 and stores 1-based positions; the other widgets of the caller shift to make room, and the order is renumbered visible widgets first, then widgets the caller's roles no longer grant.

  • omitted — 0 — moves the widget to the first position.

  • negative or beyond the last position — Not validated; stored as given (+1). Sorting still works but positions are no longer 1..N.

Responses