Skip to main content

​
Overview

The Announcements API allows administrators to create, update, and manage site-wide announcements that are displayed to users during a specified time period.
All announcement endpoints require administrator authentication and permissions.

​
Authentication

All endpoints require:
  • Valid authentication token
  • Administrator role/permissions
  • Bearer token in Authorization header
Authorization: Bearer YOUR_ACCESS_TOKEN

​
Announcement Structure

Announcements contain the following fields:
FieldTypeDescription
announcement_idintegerUnique identifier for the announcement
contentstringThe announcement message content
start_atdatetimeWhen the announcement becomes active
end_atdatetimeWhen the announcement expires
created_atdatetimeWhen the announcement was created
updated_atdatetimeWhen the announcement was last updated

​
Endpoints

​
List Announcements

Get a paginated list of current announcements. 
GET /api/admin/announcement
By default, this endpoint returns only current announcements (where the current time is between start_at and end_at).
Query Parameters:
  • Standard pagination and filtering parameters
  • Supports field selection and includes
Example Response: 
{
  "announcements": [
    {
      "announcement_id": 1,
      "content": "Scheduled maintenance on March 15th from 2-4 AM UTC",
      "start_at": "2026-03-01T00:00:00.000000Z",
      "end_at": "2026-03-15T04:00:00.000000Z",
      "created_at": "2026-02-28T10:30:00.000000Z",
      "updated_at": "2026-02-28T10:30:00.000000Z"
    }
  ]
}

​
Create Announcement

Create a new announcement. 
POST /api/admin/announcement
Request Body: 
{
  "content": "New feature released: Advanced search filters!",
  "start_at": "2026-03-03T00:00:00Z",
  "end_at": "2026-03-10T23:59:59Z"
}
Required Fields:
  • content - The announcement message
  • start_at - Start date/time for the announcement
  • end_at - End date/time for the announcement
Example Response: 
{
  "announcement": {
    "announcement_id": 2,
    "content": "New feature released: Advanced search filters!",
    "start_at": "2026-03-03T00:00:00.000000Z",
    "end_at": "2026-03-10T23:59:59.000000Z",
    "created_at": "2026-03-03T12:00:00.000000Z",
    "updated_at": "2026-03-03T12:00:00.000000Z"
  }
}

​
Get Announcement

Retrieve a specific announcement by ID. 
GET /api/admin/announcement/{id}
Path Parameters:
  • id - The announcement ID
Example Response: 
{
  "announcement": {
    "announcement_id": 1,
    "content": "Scheduled maintenance on March 15th from 2-4 AM UTC",
    "start_at": "2026-03-01T00:00:00.000000Z",
    "end_at": "2026-03-15T04:00:00.000000Z",
    "created_at": "2026-02-28T10:30:00.000000Z",
    "updated_at": "2026-02-28T10:30:00.000000Z"
  }
}

​
Update Announcement

Update an existing announcement. 
PUT /api/admin/announcement/{id}
Path Parameters:
  • id - The announcement ID
Request Body: 
{
  "content": "Updated: Maintenance rescheduled to March 16th",
  "start_at": "2026-03-01T00:00:00Z",
  "end_at": "2026-03-16T04:00:00Z"
}
Example Response: 
{
  "announcement": {
    "announcement_id": 1,
    "content": "Updated: Maintenance rescheduled to March 16th",
    "start_at": "2026-03-01T00:00:00.000000Z",
    "end_at": "2026-03-16T04:00:00.000000Z",
    "created_at": "2026-02-28T10:30:00.000000Z",
    "updated_at": "2026-03-03T14:00:00.000000Z"
  }
}

​
Delete Announcement

Permanently delete an announcement. 
DELETE /api/admin/announcement/{id}
Path Parameters:
  • id - The announcement ID
This operation permanently deletes the announcement and cannot be undone.
Example Response: 
{
  "message": "The Announcement '1' was deleted."
}

​
Usage Examples

​
Creating a Maintenance Announcement

curl -X POST https://api.animethemes.moe/api/admin/announcement \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Scheduled maintenance: The site will be down for 2 hours starting at 2 AM UTC",
    "start_at": "2026-03-15T00:00:00Z",
    "end_at": "2026-03-15T04:00:00Z"
  }'

​
Updating an Announcement

curl -X PUT https://api.animethemes.moe/api/admin/announcement/1 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Maintenance window extended by 1 hour",
    "end_at": "2026-03-15T05:00:00Z"
  }'

​
Best Practices

Set start_at slightly before the actual event to ensure users see the announcement in advance. For maintenance, consider starting the announcement 24-48 hours early.
Keep announcement content concise and actionable. Include specific times with timezone information (UTC recommended).
Regularly delete expired announcements to keep the database clean. Consider setting up automated cleanup for announcements older than 30 days past their end_at date.

Feature Flags

Manage feature toggles

Database Dumps

Download database backups

Build docs developers (and LLMs) love

Get started for freeTalk to us