Appearance
Announcements API
Product news ("What's new") written by installation administrators and read by everyone.
All paths are relative to https://your-site.com/api/v1. Send Authorization: Bearer <token> and Accept: application/json; see authentication and errors.
| Method | Path | What it does |
|---|---|---|
| GET | /announcements | Published announcements ("What's new"), newest first, 10 a page |
| POST | /announcements/seen | Marks every published announcement as read |
| GET | /admin/announcements | Every announcement, drafts first (administrators), 20 a page |
| POST | /admin/announcements | Writes an announcement (administrators); a draft unless publish |
| POST | /admin/announcements/{announcement} | Changes an announcement with an upload (multipart; administrators) |
| PATCH | /admin/announcements/{announcement} | Changes an announcement (administrators) |
| DELETE | /admin/announcements/{announcement} | Deletes an announcement and its image (administrators) |
GET /announcements
Published announcements ("What's new"), newest first, 10 a page
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | Minimum 1. |
Responses
- 200 —
data: id, title, body (plain text), kind (feature, improvement, fix, news), image_url, published_at, emailed_at;meta.unread: how many are newer than the person's last look.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].id | integer | ||
data[].title | string | ||
data[].body | string | Plain text; blank lines between paragraphs. | |
data[].kind | string | One of: feature, improvement, fix, news. | |
data[].image_url | string, nullable | ||
data[].published_at | string (date-time), nullable | ||
data[].emailed_at | string (date-time), nullable | ||
meta | object |
bash
curl -X GET "https://your-site.com/api/v1/announcements" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"POST /announcements/seen
Marks every published announcement as read
Responses
- 204 — Done.
bash
curl -X POST "https://your-site.com/api/v1/announcements/seen" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"GET /admin/announcements
Every announcement, drafts first (administrators), 20 a page
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
page | query | integer | Minimum 1. |
Responses
- 200 — The announcements with
meta.total. - 403 — Not allowed (not an administrator, or outside the token's abilities).
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].id | integer | ||
data[].title | string | ||
data[].body | string | Plain text; blank lines between paragraphs. | |
data[].kind | string | One of: feature, improvement, fix, news. | |
data[].image_url | string, nullable | ||
data[].published_at | string (date-time), nullable | ||
data[].emailed_at | string (date-time), nullable | ||
meta | object |
bash
curl -X GET "https://your-site.com/api/v1/admin/announcements" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"POST /admin/announcements
Writes an announcement (administrators); a draft unless publish
Request body
multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
title | string | At most 150 characters. | |
body | string | At most 5000 characters. | |
kind | string | One of: feature, improvement, fix, news. | |
image | string (binary) | A picture up to 5 MB (stored as a JPEG at most 1600 px wide). | |
remove_image | boolean | ||
publish | boolean | true publishes now (keeps the first date); false makes it a draft. | |
email | boolean | Email it to everyone when published (once). |
Responses
- 201 — Written.
- 403 — Not allowed (not an administrator, or outside the token's abilities).
- 422 —
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.title | string | ||
data.body | string | Plain text; blank lines between paragraphs. | |
data.kind | string | One of: feature, improvement, fix, news. | |
data.image_url | string, nullable | ||
data.published_at | string (date-time), nullable | ||
data.emailed_at | string (date-time), nullable |
bash
curl -X POST "https://your-site.com/api/v1/admin/announcements" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json" \
-F "title=…" \
-F "body=…" \
-F "kind=…" \
-F "image=…"POST /admin/announcements/{announcement}
Changes an announcement with an upload (multipart; administrators)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
announcement | path | integer | yes |
Request body
multipart/form-data
| Field | Type | Required | Description |
|---|---|---|---|
title | string | At most 150 characters. | |
body | string | At most 5000 characters. | |
kind | string | One of: feature, improvement, fix, news. | |
image | string (binary) | A picture up to 5 MB (stored as a JPEG at most 1600 px wide). | |
remove_image | boolean | ||
publish | boolean | true publishes now (keeps the first date); false makes it a draft. | |
email | boolean | Email it to everyone when published (once). |
Responses
- 200 — Changed.
- 403 — Not allowed (not an administrator, or outside the token's abilities).
- 422 —
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.title | string | ||
data.body | string | Plain text; blank lines between paragraphs. | |
data.kind | string | One of: feature, improvement, fix, news. | |
data.image_url | string, nullable | ||
data.published_at | string (date-time), nullable | ||
data.emailed_at | string (date-time), nullable |
bash
curl -X POST "https://your-site.com/api/v1/admin/announcements/{announcement}" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json" \
-F "title=…" \
-F "body=…" \
-F "kind=…" \
-F "image=…"PATCH /admin/announcements/{announcement}
Changes an announcement (administrators)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
announcement | path | integer | yes |
Request body
application/json
| Field | Type | Required | Description |
|---|---|---|---|
title | string | At most 150 characters. | |
body | string | At most 5000 characters. | |
kind | string | One of: feature, improvement, fix, news. | |
image | string (binary) | A picture up to 5 MB (stored as a JPEG at most 1600 px wide). | |
remove_image | boolean | ||
publish | boolean | true publishes now (keeps the first date); false makes it a draft. | |
email | boolean | Email it to everyone when published (once). |
Responses
- 200 — Changed.
- 403 — Not allowed (not an administrator, or outside the token's abilities).
- 422 —
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.title | string | ||
data.body | string | Plain text; blank lines between paragraphs. | |
data.kind | string | One of: feature, improvement, fix, news. | |
data.image_url | string, nullable | ||
data.published_at | string (date-time), nullable | ||
data.emailed_at | string (date-time), nullable |
bash
curl -X PATCH "https://your-site.com/api/v1/admin/announcements/{announcement}" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"title":"text","body":"text","kind":"feature","image":"text","remove_image":true,"publish":true,"email":true}'DELETE /admin/announcements/{announcement}
Deletes an announcement and its image (administrators)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
announcement | path | integer | yes |
Responses
- 204 — Deleted.
- 403 — Not allowed (not an administrator, or outside the token's abilities).
bash
curl -X DELETE "https://your-site.com/api/v1/admin/announcements/{announcement}" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"