Documentation Index¶

Fetch the complete documentation index at: https://makakoo-traylinx-35.mintlify.app/llms.txt Use this file to discover all available pages before exploring further.

User Settings Service¶

User preferences and cross-device settings synchronization API.

The User Settings service stores user preferences and sidebar navigation state server-side, enabling cross-device synchronization. It is served by the Organizations & Metrics microservice at REACT_APP_ORGANIZATIONS_API_BASE_URL (default: https://api.traylinx.com/ma-metrics-wsp-ms/v1/api).

All requests require Api-Key and Authorization: Bearer <token> headers.

Get User Settings¶

http theme={null} GET https://api.traylinx.com/ma-metrics-wsp-ms/v1/api/user_settings

Return the authenticated user’s settings, including the sidebar data structure used to render navigation. A single call to this endpoint can replace multiple separate API calls at login time.

Client identifier. Use "web" for browser clients. Defaults to "web".

Comma-separated additional data to include. Pass "dashboard" to include dashboard cache data alongside sidebar data.

```bash theme={null} curl "https://api.traylinx.com/ma-metrics-wsp-ms/v1/api/user_settings?client=web" \ -H "Authorization: Bearer " \ -H "Api-Key: "

<ResponseField name="sidebar" type="object">
  Sidebar navigation data. Ready for direct rendering — no transformation required.

  <Expandable title="sidebar fields">
    <ResponseField name="sidebar.organizations" type="array">
      List of organizations the user belongs to.

      <Expandable title="Organization entry">
        <ResponseField name="id" type="integer | string">
          Organization ID (integer for legacy numeric IDs, UUID string for newer organizations).
        </ResponseField>

        <ResponseField name="name" type="string">
          Organization name.
        </ResponseField>

        <ResponseField name="currentUserRole" type="string">
          The authenticated user’s role in this organization: `OWNER`, `ADMIN`, `MEMBER`, or `VIEWER`.
        </ResponseField>

        <ResponseField name="meta.can" type="object">
          Permission map for UI element visibility.

          <Expandable title="can fields">
            <ResponseField name="organization.manageSettings" type="boolean">
              Whether the user can manage organization settings.
            </ResponseField>

            <ResponseField name="project.create" type="boolean">
              Whether the user can create projects in this organization.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="pinned_items" type="array">
          Projects pinned by the user for quick access in this organization.

          <Expandable title="Pinned item fields">
            <ResponseField name="type" type="string">
              Always `"project"`.
            </ResponseField>

            <ResponseField name="id" type="integer">
              Project ID.
            </ResponseField>

            <ResponseField name="name" type="string">
              Project name.
            </ResponseField>

            <ResponseField name="position" type="integer">
              Zero-indexed position in the pinned list.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="projects" type="array">
          All projects accessible to the user within this organization.

          <Expandable title="Project entry">
            <ResponseField name="id" type="integer">
              Project ID.
            </ResponseField>

            <ResponseField name="name" type="string">
              Project name.
            </ResponseField>

            <ResponseField name="is_default" type="boolean">
              Whether this is the organization’s default project.
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="current_organization_id" type="integer | string">
  The user’s last-selected organization ID, synced across devices.
</ResponseField>

<ResponseField name="current_project_id" type="integer | string">
  The user’s last-selected project ID, synced across devices.
</ResponseField>

<ResponseField name="language" type="string">
  The user’s preferred language code (e.g., `"en"`).
</ResponseField>

<ResponseField name="theme" type="string">
  The user’s preferred theme: `"light"` or `"dark"`.
</ResponseField>

<ResponseField name="sidebar_open" type="boolean">
  Whether the sidebar is open.
</ResponseField>

<ResponseField name="dashboard" type="object">
  Dashboard cache data (only present when `includes=dashboard`).
</ResponseField>

**Example sidebar response:**

```json  theme={null}
{
  "sidebar": {
    "organizations": [
      {
        "id": 123,
        "name": "Makakoo",
        "currentUserRole": "ADMIN",
        "meta": {
          "can": {
            "organization": { "manageSettings": true },
            "project": { "create": true }
          }
        },
        "pinned_items": [
          { "type": "project", "id": 1, "name": "sleepbananas", "position": 0 }
        ],
        "projects": [
          { "id": 1, "name": "sleepbananas", "is_default": true },
          { "id": 2, "name": "My First Project", "is_default": false }
        ]
      }
    ]
  },
  "current_organization_id": 123,
  "current_project_id": 1,
  "language": "en",
  "theme": "light",
  "sidebar_open": true
}

Update User Settings¶

http theme={null} PATCH https://api.traylinx.com/ma-metrics-wsp-ms/v1/api/user_settings

Update one or more settings for the authenticated user. Changes are synced immediately to the server; the client also updates localStorage so the UI reflects the change without waiting for the API response.

Client identifier. Defaults to "web".

User’s preferred theme: "light" or "dark".

User’s preferred language code (e.g., "en", "es").

Whether the sidebar should be open.

The ID of the currently active organization. Accepts both integer and UUID formats.

The ID of the currently active project.

```bash theme={null} curl -X PATCH "https://api.traylinx.com/ma-metrics-wsp-ms/v1/api/user_settings?client=web" \ -H "Authorization: Bearer " \ -H "Api-Key: " \ -H "Content-Type: application/json" \ -d '{ "theme": "dark", "current_organization_id": 123, "current_project_id": 1 }'

**Response:** `200 OK`.

<Note>
  To avoid excessive API calls when the user changes settings rapidly, the client debounces calls to this endpoint with a 500ms delay. Build the same behaviour into custom integrations.
</Note>

***

## Update Pinned Projects

<CodeGroup>
  ```http  theme={null}
  PATCH https://api.traylinx.com/ma-metrics-wsp-ms/v1/api/user_settings
  ```
</CodeGroup>

Update the list of pinned projects for a specific organization. Pinned projects are shared across all clients (devices) for the same user.

<ParamField query="client" type="string">
  Client identifier. Defaults to `"web"`.
</ParamField>

<ParamField body="setting_key" type="string" required>
  Must be `"sidebar"`.
</ParamField>

<ParamField body="organization_id" type="integer" required>
  The organization ID whose pinned projects you are updating.
</ParamField>

<ParamField body="pinned_project_ids" type="array" required>
  Ordered array of project IDs (integers) to pin. The position in the array determines display order.
</ParamField>

```bash  theme={null}
curl -X PATCH "https://api.traylinx.com/ma-metrics-wsp-ms/v1/api/user_settings?client=web" \
  -H "Authorization: Bearer <token>" \
  -H "Api-Key: <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "setting_key": "sidebar",
    "organization_id": 123,
    "pinned_project_ids": [1, 5, 12]
  }'

Mark Onboarding Step¶

http theme={null} PATCH https://api.traylinx.com/ma-metrics-wsp-ms/v1/api/user_settings/onboarding/{stepId}

Record completion of an onboarding step or update its state.

The onboarding step identifier, e.g., "sentinel_pass_discovered" or "is_hidden".

Client identifier. Defaults to "web".

The value to set for the step. Defaults to true.

bash theme={null} curl -X PATCH "https://api.traylinx.com/ma-metrics-wsp-ms/v1/api/user_settings/onboarding/sentinel_pass_discovered?client=web" \ -H "Authorization: Bearer <token>" \ -H "Api-Key: <your_api_key>" \ -H "Content-Type: application/json" \ -d '{"value": true}'

Response: 200 OK on success, false return value from the service on error (non-throwing).

Cross-Device Sync Behaviour¶

User settings follow a local-first strategy:

On login, call GET /user_settings?client=web to load the latest settings and sidebar data from the server.
Write settings to localStorage immediately for fast local reads.
When a setting changes, update localStorage first, then call PATCH /user_settings in the background.
API call failures are logged as warnings and do not affect the local state. The client continues to function using localStorage when the API is unavailable.
Debounce rapid setting changes at 500ms to avoid excessive API traffic.

ID Validation¶

Organization and project IDs are validated before being sent to the API:

UUID format (8-4-4-4-12 hex characters): sent as a string.
Numeric format: parsed as an integer.
Invalid or empty values: converted to null and omitted from the payload.

Built with Mintlify.