Preferences

What preferences are

Preferences are one document per user. The API reads callbacks when it creates a job. ui and defaults are stored and returned for clients. Job creation does not read them.

GET returns 200 and an empty document when you have never saved one. It is not a 404.

PUT replaces the document. Send ui, callbacks, and defaults together. A group you omit is cleared. The response is the same shape as GET, plus issues when a saved webhook can no longer be used.

Any authenticated key can read and write preferences. Saving a phase that names a URL or webhook requires the callbacks permission. A body with no destinations does not.

UI

ui is read by the app. These values do not change a request.

In the app, Settings then Preferences edits this document. The webhook list on that page is the same resource as Webhooks.

Default callbacks

callbacks.apply controls whether saved destinations are copied onto a new job.

A phase the request sets is kept. Saved defaults exist for scans, captures, surveys, and permutations. Each phase is a url or a callback_id, not both. Tasks do not use these defaults. See Callbacks.

GET adds issues when a saved callback_id is missing or inactive. Each issue has path (for example callbacks.scans.success), callback_id, and reason (not_found or inactive). Issues are computed on read and are not stored. That phase is skipped when a job is created. The job is still created.

An unknown or inactive webhook on the PUT body is 422. A phase that sets both url and callback_id is 422. An unknown theme, density, landing_page, time_zone, or apply is 422.

Scan defaults

defaults.scan is stored for clients. The scan form applies fingerprint and default_ports. The API does not copy these fields onto POST /scans.

curl -sS -X PUT "https://api.efflux.io/v3/preferences" \
  -H "Authorization: Bearer $EFFLUX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ui": {
      "theme": "dark",
      "density": "compact",
      "landing_page": "scans",
      "time_zone": "America/Los_Angeles"
    },
    "callbacks": {
      "apply": "when_absent",
      "scans": {
        "success": { "callback_id": "whook_abc123" },
        "fail": { "callback_id": "whook_abc123" }
      }
    },
    "defaults": {
      "scan": { "fingerprint": false }
    }
  }'