Settings API

Settings for your business, this workspace and each module.

Module code settings · 1 actions · 2 data models · 1 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: settings (everything), settings:read (read only) or settings:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

settings.set

Change a setting — Writes one setting at the organization, workspace or module layer.

Needs settings:manage · changes data

• Canonical address: POST /api/v1/actions/settings.set

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: settings.changed

What it writes: setting (upsert) — Writes the setting

curl -X POST https://app.getera.io/api/v1/settings/actions/set \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"layer":"organization","key":"Key","value":"Value"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "settings.changed"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.settings.set({
  layer: "organization",
  key: "Key",
  value: "Value"
})

era settings set \
  --layer "organization" \
  --key "Key" \
  --value "Value"

{
  "name": "era__settings__set",
  "arguments": {
    "layer": "organization",
    "key": "Key",
    "value": "Value"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold settings:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 module_required, unknown_setting, invalid_value · 429 slow down

Data models

NumberSequence

Table number_sequence · Resource number_sequences

• GET /api/v1/number_sequences
• GET /api/v1/number_sequences/{id}

Primary key: id

Unique: workspace_id, code

Setting

Table setting · Resource settings

• GET /api/v1/settings
• GET /api/v1/settings/{id}

Primary key: id

Checks:

• CHECK (((module_code IS NULL) OR (workspace_id IS NOT NULL)))

Events

Workflows and webhooks react to these events.