The organization

The community itself. The app calls it a community; the API calls it the organization. There is exactly one: the community the key belongs to.

Read it: GET /organization

curl "$API/organization" -H "Authorization: Bearer $KEY"

Answers 200 OK:

{
  "id": 41,
  "slug": "elm-street",
  "name": "Elm Street Neighbours",
  "short_description": "Neighbours helping neighbours",
  "aim": null,
  "domain": null,
  "brand_color": "#1D4ED8",
  "home_scheme": "split",
  "icon_style": "initials",
  "initials": "ES",
  "photo_url": "https://zensocial.app/rails/active_storage/blobs/redirect/…/cover.jpg"
}
Field Type Meaning
id number The community's id.
slug text The community's short name in its web address. Only changed in the app.
name text The community's name.
short_description text or null One line under the name.
aim text or null What the community is for. Only used by communities that run with sociocratic governance (switched on in the app); always null otherwise.
domain text or null What the community decides. Sociocratic communities only, like aim; always null otherwise.
brand_color text or null The community's colour, # and six hex digits ("#1D4ED8"). null: the app picks one from the photo or the name.
home_scheme text or null How the home page combines colours: mono, analogous, complementary, split or triadic. null means the app's default, split.
icon_style text The community's icon on phones: initials (its initials on its colour), photo (its photo) or upload (an icon uploaded in the app; there is no icon upload in the API).
initials text or null 1 to 5 characters for the initials icon. null: taken from the name.
photo_url text or null The community's photo, as an address. null while it shows a stock photo.

Change it: PATCH /organization

Send only the fields you want to change. Answers 200 OK with the whole organization, as above.

curl -X PATCH "$API/organization" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name": "Elm Street Neighbours", "short_description": "Neighbours helping neighbours", "brand_color": "#1D4ED8", "home_scheme": "triadic"}'
Field Rules
name Cannot be empty, and must be unique on all of Zen Social (not just in this community, and regardless of capitals).
short_description Text.
brand_color # and six hex digits. An empty string clears it.
home_scheme mono, analogous, complementary, split or triadic. An empty string goes back to the default.
icon_style initials, photo or upload.
initials 1 to 5 characters. An empty string goes back to initials taken from the name.
aim Up to 200 characters. Sociocratic communities only; ignored for the others.
domain What the community decides, up to 500 characters. Sociocratic communities only; ignored for the others.
photo A photo file, sent as a multipart upload (below).
photo_url The address of a photo for Zen Social to fetch (below).

The slug, the kind of circle, who may join, and the parent are not offered: they change only in the app. Fields the API does not know are ignored without an error, so check the answer to see what was saved.

A wrong value answers 422 and changes nothing:

{"error": "invalid", "details": {"brand_color": ["is invalid"]}}

The photo

Two ways, both on PATCH /organization:

  • photo_url, in a JSON body: a public http or https address of a PNG, JPEG, GIF or WebP image, at most 5 MB. Zen Social fetches it itself. SVG images, web pages and addresses on private networks are refused.
  curl -X PATCH "$API/organization" \
    -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
    -d '{"photo_url": "https://example.org/our-group-cover.jpg"}'
  • photo, a multipart upload of a PNG, JPEG, GIF or WebP file. Other fields can go in the same form.
  curl -X PATCH "$API/organization" \
    -H "Authorization: Bearer $KEY" \
    -F "photo=@cover.jpg"

If both are sent, the upload wins. A photo that cannot be used answers 422 with the reason under details.photo (for example "could not be fetched as an image"), and nothing in the request is saved.

Who may

Every key may read and change its organization: only owners and admins of a community can make a key for it.