Skip to content

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.

MethodPathWhat it does
GET/announcementsPublished announcements ("What's new"), newest first, 10 a page
POST/announcements/seenMarks every published announcement as read
GET/admin/announcementsEvery announcement, drafts first (administrators), 20 a page
POST/admin/announcementsWrites 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 ​

NameInTypeRequiredDescription
pagequeryintegerMinimum 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
FieldTypeRequiredDescription
dataobject[]
data[].idinteger
data[].titlestring
data[].bodystringPlain text; blank lines between paragraphs.
data[].kindstringOne of: feature, improvement, fix, news.
data[].image_urlstring, nullable
data[].published_atstring (date-time), nullable
data[].emailed_atstring (date-time), nullable
metaobject
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 ​

NameInTypeRequiredDescription
pagequeryintegerMinimum 1.

Responses ​

  • 200 — The announcements with meta.total.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
Response fields
FieldTypeRequiredDescription
dataobject[]
data[].idinteger
data[].titlestring
data[].bodystringPlain text; blank lines between paragraphs.
data[].kindstringOne of: feature, improvement, fix, news.
data[].image_urlstring, nullable
data[].published_atstring (date-time), nullable
data[].emailed_atstring (date-time), nullable
metaobject
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

FieldTypeRequiredDescription
titlestringAt most 150 characters.
bodystringAt most 5000 characters.
kindstringOne of: feature, improvement, fix, news.
imagestring (binary)A picture up to 5 MB (stored as a JPEG at most 1600 px wide).
remove_imageboolean
publishbooleantrue publishes now (keeps the first date); false makes it a draft.
emailbooleanEmail it to everyone when published (once).

Responses ​

  • 201 — Written.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.titlestring
data.bodystringPlain text; blank lines between paragraphs.
data.kindstringOne of: feature, improvement, fix, news.
data.image_urlstring, nullable
data.published_atstring (date-time), nullable
data.emailed_atstring (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 ​

NameInTypeRequiredDescription
announcementpathintegeryes

Request body ​

multipart/form-data

FieldTypeRequiredDescription
titlestringAt most 150 characters.
bodystringAt most 5000 characters.
kindstringOne of: feature, improvement, fix, news.
imagestring (binary)A picture up to 5 MB (stored as a JPEG at most 1600 px wide).
remove_imageboolean
publishbooleantrue publishes now (keeps the first date); false makes it a draft.
emailbooleanEmail it to everyone when published (once).

Responses ​

  • 200 — Changed.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.titlestring
data.bodystringPlain text; blank lines between paragraphs.
data.kindstringOne of: feature, improvement, fix, news.
data.image_urlstring, nullable
data.published_atstring (date-time), nullable
data.emailed_atstring (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 ​

NameInTypeRequiredDescription
announcementpathintegeryes

Request body ​

application/json

FieldTypeRequiredDescription
titlestringAt most 150 characters.
bodystringAt most 5000 characters.
kindstringOne of: feature, improvement, fix, news.
imagestring (binary)A picture up to 5 MB (stored as a JPEG at most 1600 px wide).
remove_imageboolean
publishbooleantrue publishes now (keeps the first date); false makes it a draft.
emailbooleanEmail it to everyone when published (once).

Responses ​

  • 200 — Changed.
  • 403 — Not allowed (not an administrator, or outside the token's abilities).
  • 422 —
Response fields
FieldTypeRequiredDescription
dataobject
data.idinteger
data.titlestring
data.bodystringPlain text; blank lines between paragraphs.
data.kindstringOne of: feature, improvement, fix, news.
data.image_urlstring, nullable
data.published_atstring (date-time), nullable
data.emailed_atstring (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 ​

NameInTypeRequiredDescription
announcementpathintegeryes

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"

Replora: see what your visitors see.