Skip to main content

Settings

Manage user-specific report view settings and preferences.

Overview​

User settings allow each user to customize their view of a report without affecting other users. Settings are stored per user, per report and include view preferences, column visibility, sort orders, and other UI state.

GET /api/reports/{id}/settings​

Get the current user's settings for a report.

Authentication: Required

Path Parameters:

ParameterTypeDescription
idstringReport ID

Response:

The calling user's saved settings for this report.

Get report settingsGET /api/reports/admin:sales-overview/settings
The calling user’s saved settings for this report, or an empty object when none are saved.
Response · 200
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/reports/admin%3Asales-overview/settings"
    },
    "inf:restore": {
      "href": "https://informer.example.com/api/reports/admin%3Asales-overview/settings/_restore"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "datasetId": null,
  "reportId": "00000000-0000-4000-8000-000000000002",
  "queryId": null,
  "templateId": null,
  "userId": "admin",
  "settings": {
    "pageSize": 50,
    "defaultView": "chart"
  },
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "tenant": "acme",
  "snapshots": null
}
Captured from the API examples test suite; ids and timestamps are normalized.

Default Behavior:

Returns an empty object {} if no settings have been saved.

Use Case:

Load user-specific view preferences when opening a report.

PUT /api/reports/{id}/settings​

Save or update the current user's settings for a report.

Authentication: Required

Path Parameters:

ParameterTypeDescription
idstringReport ID

Request Body:

{
  "columns": ["name", "value", "date"],
  "sortBy": "date",
  "sortDir": "desc",
  "filters": {
    "region": "West"
  },
  "viewMode": "chart",
  "customProperty": "any-value"
}

Response:

Echoes the saved settings object.

Save report settingsPUT /api/reports/admin:sales-overview/settings
Per-user, per-report settings (the body is stored verbatim under the caller’s UserSettings). Echoes the submitted body.
Request body
{
  "defaultView": "chart",
  "pageSize": 50
}
Response · 200
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/reports/admin%3Asales-overview/settings"
    },
    "inf:restore": {
      "href": "https://informer.example.com/api/reports/admin%3Asales-overview/settings/_restore"
    }
  },
  "defaultView": "chart",
  "pageSize": 50
}
Captured from the API examples test suite; ids and timestamps are normalized.

Behavior:

  • Creates a new UserSettings entry if none exists
  • Updates existing settings if already present
  • Settings are scoped to the current user and report
  • Replaces all settings (not merged)

Use Case:

Persist user view preferences when they make changes to report display.

POST /api/reports/{id}/settings/_restore​

Delete the current user's settings, restoring defaults.

Authentication: Required

Path Parameters:

ParameterTypeDescription
idstringReport ID

Response:

Responds 200 on success.

Restore default report settingsPOST /api/reports/admin:sales-overview/settings/_restore
Deletes the caller’s saved settings so the report falls back to its defaults. Responds 200.
Response · 200 · no body
Captured from the API examples test suite; ids and timestamps are normalized.

Behavior:

  • Removes the user's settings entry for this report
  • Next GET will return empty object (defaults)
  • Does not affect other users' settings

Use Case:

Reset report view to system defaults.

Settings Structure​

Settings are free-form JSON objects that can contain any properties. Common patterns include:

View Configuration​

{
  "viewMode": "table",
  "layout": "grid",
  "theme": "dark"
}

Column Management​

{
  "columns": ["id", "name", "status"],
  "columnWidths": {
    "id": 100,
    "name": 200,
    "status": 150
  },
  "hiddenColumns": ["internal_id"]
}

Sorting & Filtering​

{
  "sortBy": "createdAt",
  "sortDir": "desc",
  "filters": {
    "status": "active",
    "region": ["West", "East"]
  }
}

Pagination​

{
  "pageSize": 50,
  "currentPage": 1
}
Settings vs Report Definition

User settings are for personal preferences (sort order, visible columns, UI state), while the report definition (defn) contains the actual report structure (visuals, datasets, layout). Settings don't affect other users or the published report.

Lifecycle Notes​

  • Settings are automatically deleted when a draft is committed (via POST /api/reports/\{id\}/draft/_commit)
  • This ensures all users see the updated report with fresh defaults after structural changes
  • Users can re-save their preferences after viewing the updated report