# 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`

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

Answers `200 OK`:

```json
{
  "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.

```sh
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:

```json
{"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.

  ```sh
  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.

  ```sh
  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.