Organization settings and addresses

Two hundred and six behavioural settings live at the organization, and the addresses your content is read at live beside them. Both are plain API doors, and neither had a guide — so the only way to find out which keys exist was to read the reference page for PUT /orgs/{orgId}/settings/{key} and guess.

The catalogue

curl -sS -A 'my-app/1.0' -H "Authorization: Bearer $TOKEN" \
  https://forumulate.com/api/orgs/$ORG/settings

Every key, with what it is for and what it currently is:

{
  "key": "community.max_tags_per_topic",
  "label": "Tags allowed per topic",
  "category": "community",
  "type": "integer",
  "default": 5,
  "min": 0,
  "max": 50,
  "description": "Maximum number of tags allowed on a new topic (0 disables tags).",
  "value": 5,
  "isDefault": true     // nobody here has changed it
}

isDefault is the field worth reading. A setting your organization has never touched reports the platform default and says so, which is how you tell "we chose 5" from "nobody chose anything".

The categories, and roughly how many keys each holds: community (124), users (23), email (18), chat (11), files (10), general (8), security (5), search (3), status (2), careers (1), seo (1).

Reading and writing one

# write
curl -sS -A 'my-app/1.0' -H "Authorization: Bearer $TOKEN" \
  -X PUT -H 'content-type: application/json' -d '{"value": 20}' \
  https://forumulate.com/api/orgs/$ORG/settings/community.min_post_length

# put it back to the platform default
curl -sS -A 'my-app/1.0' -H "Authorization: Bearer $TOKEN" \
  -X DELETE https://forumulate.com/api/orgs/$ORG/settings/community.min_post_length

value is a boolean, a number or a string, matching the key's type. A value outside a key's min/max is a 422 that names the bounds. DELETE clears the setting rather than disabling the feature — the key goes back to not being stated, which is not the same as setting it to false.

Where a space can disagree

Some decisions belong to one space rather than the whole organization. The rule, everywhere it applies:

space override  →  org default  →  today's behaviour

"Today's behaviour" is what the product does when nobody has said anything, so an organization that sets none of these sees no change at all. A space that has chosen for itself always wins, and a shape override on a piece wins over both.

GET /orgs/{orgId}/spaces/{spaceId}/discovery is the pattern to copy if you are building a console of your own: it answers the effective value and both inputs, so you can render "inherited from the organization" instead of guessing.

Your organization's address

Your organization's slug is the segment in every platform URL your content is read at — forumulate.com/p/<org>/<space>/<page> — and in the addresses the API hands back.

curl -sS -A 'my-app/1.0' -H "Authorization: Bearer $TOKEN" \
  -X PATCH -H 'content-type: application/json' -d '{"slug": "acme"}' \
  https://forumulate.com/api/orgs/$ORG/slug

{ "previous": "acme-inc", "slug": "acme" }

A space has the same door at PATCH /orgs/{orgId}/spaces/{spaceId}/slug. Both answer with what the name was, so a migration can record it.

Both names are also reserved against a list: api and docs are ours, and a reserved name answers 409 space.slug_reserved rather than space.slug_taken — a retry with a suffix will never free it.

Renaming is safe for links that already exist: the ID form of every address goes on resolving for ever, and a page's own rename leaves a redirect behind. What a rename does change is the canonical URL a search engine has indexed, so do it once and early rather than twice.

What's next

• API conventions — errors, paging, idempotency, the version header.

• Team and permissions — who may change any of this.

• Privacy, GDPR and data requests — the export and erasure doors.