API reference

Settings

Two kinds of settings: the workspace's, which owners set and every member shares, and each user's own preferences. The portal's Settings › Workspace and Settings › Preferences pages call exactly these routes.

What is shared and what is yours

Setting	Scope	Who changes it
Workspace name and company	Tenant-shared	Owners
`default_currency` (dashboard filter, generate default)	Tenant-shared	Owners
`default_time_zone` (for members who chose none)	Tenant-shared	Owners
Environment label and colour	Tenant-shared	Owners
Workspace flow default	Tenant-shared (see Flows)	Owners
Time zone, language, date format, clock, page size, default disputes tab, theme	Per user, in this workspace	Each user
`dm_prefs` cookie	Per browser	Whoever sets the cookie; overrides the preferences in that browser only

Changing a tenant-shared setting changes it for every member and every concurrent test run in the workspace, so tests should not change them; per-user values a test needs go in the dm_prefs cookie.

Workspace settings

Route	Who
`GET /v1/settings/workspace`	Any member, and any API key of the workspace. Also in GET /v1/auth/me as workspace_settings.
`PATCH /v1/settings/workspace`	An owner's signed-in session only (`workspace.write`, never on a key). Audited `workspace_settings.update` with `{from, to}` per changed field.

GET /v1/settings/workspace

{"object":"workspace_settings","id":"…","name":"Acme sandbox","company":"Acme Ltd",
 "default_currency":"EUR","default_time_zone":"Europe/Lisbon",
 "environment_label":"STAGING-QA","environment_color":"#d97706",
 "version":3,"updated_at":"2026-10-28T09:12:44.120Z"}

Field	Values
`name`	The workspace name (trimmed; cannot be null).
`company`	Free text; null or empty clears it.
`default_currency`	ISO 4217, upper case. `null`: none, the dashboard sums every currency as before.
`default_time_zone`	IANA zone for members who did not choose one. `null`: UTC.
`environment_label`	Up to 24 characters, shown in the workspace menu, the top bar, a stripe in its colour, the tab title and every destructive confirm, so you never act in the wrong workspace (see Workspaces and environments). Cosmetic: nothing depends on it. null or empty clears it.
`environment_color`	`#rrggbb` (stored lower case); `null` is the default colour.
`version`	Counts the changes; 0 = never changed.

Send only the fields to change; null clears a nullable one. A body that changes nothing returns the settings and writes nothing. An empty body or a value out of range is 400 validation_failed with details[].field naming it.

Your preferences

GET /v1/me/preferences and PATCH /v1/me/preferences apply to the signed-in user in this workspace (also in GET /v1/auth/me as preferences). They are a user's own, so API keys cannot call them (401 api_key_not_allowed). Audited user_preferences.update.

Field	Values
`time_zone`	IANA zone; `null` follows the workspace.
`effective_time_zone`	Read only: `time_zone`, else the workspace's `default_time_zone`, else `UTC`. Never the browser's zone, so server and browser rendering agree.
`locale`	`en`, `pt`, `he`, `no`, `nn` or `ro`; `null`: from the URL, else English.
`date_format`	`locale` or `iso` (ISO 8601).
`hour_cycle`	`h12` or `h23`; `null`: the language's default.
`page_size`	25, 50, 100 or 200 rows per list page.
`disputes_default_tab`	`unanswered` or `all`.
`theme`	`light`, `dark` or `system`.

PATCH /v1/me/preferences

{"time_zone": "Asia/Tokyo", "date_format": "iso", "hour_cycle": "h23"}

The dm_prefs cookie

Workers that share a synthetic account would change each other's saved preferences. Instead, a test sets dm_prefs on the portal host for its own browser context; it overrides the saved values for that browser only and changes nothing on the account.


Value	`tz=Asia/Tokyo;locale=pt;date_format=iso;hour_cycle=h23;page_size=25`, URL-encoded. Set only the keys you need.
Keys	`tz`, `locale`, `date_format`, `hour_cycle`, `page_size`, with the values above.
Invalid value	Ignored for that key, with a console warning; the saved preference applies.

The portal shows dates in the cookie's zone, else the account's, else the workspace's, else UTC. See the E2E guide for setting it from Playwright.

Dashboard metrics: currency and tz

GET /v1/metrics/overview takes two optional parameters:

Parameter	Effect
`currency`	ISO 4217, upper case. Every figure, counts included, covers only transactions and disputes in that currency. Absent: every currency, amounts summed as-is in minor units (the previous behaviour).
`tz`	IANA zone the daily series is bucketed in: `series.points[].date` is the local calendar day. Absent: UTC.

A malformed value is 400 validation_failed. The portal's dashboard passes the currency you pick (initially the workspace's default_currency) and your effective time zone.

GET /v1/metrics/overview?currency=EUR&tz=Europe/Lisbon&from=2026-10-01T00:00:00Z