Get Active Announcements

Retrieve all active (published and not expired) announcements for the current tenant with read status

GET /api/v2/admin/announcements/active

cURL

curl -X GET "https://api.example.com/api/v2/admin/announcements/active" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "tenant_id": "tenant-123",
      "title": "System Maintenance Scheduled",
      "summary": "We will be performing scheduled maintenance on our servers.",
      "content": "Our servers will be undergoing scheduled maintenance on Sunday, December 15th from 2:00 AM to 4:00 AM EST. During this time, you may experience brief service interruptions.",
      "type": "warning",
      "priority": 1,
      "status": "published",
      "is_public": false,
      "expires_at": "2024-12-16T00:00:00Z",
      "topic": "SYSTEM",
      "attachment_type": null,
      "attachment_url": null,
      "attachment_metadata": null,
      "created_at": "2024-12-11T09:30:00Z",
      "is_read": false,
      "is_dismissed": false
    },
    {
      "id": 2,
      "tenant_id": "tenant-123",
      "title": "New Feature Release",
      "summary": "We have released exciting new features!",
      "content": "Check out our new dashboard improvements and enhanced reporting capabilities.",
      "type": "success",
      "priority": 0,
      "status": "published",
      "is_public": false,
      "expires_at": null,
      "topic": "FEATURES",
      "attachment_type": "link",
      "attachment_url": "https://example.com/features",
      "attachment_metadata": {
        "button_text": "Learn More"
      },
      "created_at": "2024-12-11T14:30:00Z",
      "is_read": true,
      "is_dismissed": false
    }
  ]
}

Headers

Authorization · string · required

Bearer token for authentication

X-Tenant-ID · string · required

The tenant ID to scope the announcements

Response

success · boolean

Indicates if the request was successful

data · array

Array of active announcement objects with read status

Show announcement

id · integer

Unique identifier for the announcement

tenant_id · string

The tenant ID this announcement belongs to

title · string

The announcement title

summary · string

Brief summary of the announcement

content · string

Detailed content of the announcement

type · string

Type of announcement: info, warning, success, alert

priority · integer

Priority level: 0 for normal, 1 for high

status · string

Current status (will always be published for active announcements)

is_public · boolean

Whether the announcement is public

expires_at · string

ISO timestamp when the announcement expires

topic · string

Topic category (e.g., PROMOTIONS, SYSTEM, MAINTENANCE)

attachment_type · string

Type of attachment: image, link, button

attachment_url · string

URL of the attachment

attachment_metadata · object

Additional metadata for the attachment

created_at · string

ISO timestamp when the announcement was created

is_read · boolean

Whether the current user has read this announcement

is_dismissed · boolean

Whether the current user has dismissed this announcement

cURL

curl -X GET "https://api.example.com/api/v2/admin/announcements/active" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Tenant-ID: your-tenant-id"

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "tenant_id": "tenant-123",
      "title": "System Maintenance Scheduled",
      "summary": "We will be performing scheduled maintenance on our servers.",
      "content": "Our servers will be undergoing scheduled maintenance on Sunday, December 15th from 2:00 AM to 4:00 AM EST. During this time, you may experience brief service interruptions.",
      "type": "warning",
      "priority": 1,
      "status": "published",
      "is_public": false,
      "expires_at": "2024-12-16T00:00:00Z",
      "topic": "SYSTEM",
      "attachment_type": null,
      "attachment_url": null,
      "attachment_metadata": null,
      "created_at": "2024-12-11T09:30:00Z",
      "is_read": false,
      "is_dismissed": false
    },
    {
      "id": 2,
      "tenant_id": "tenant-123",
      "title": "New Feature Release",
      "summary": "We have released exciting new features!",
      "content": "Check out our new dashboard improvements and enhanced reporting capabilities.",
      "type": "success",
      "priority": 0,
      "status": "published",
      "is_public": false,
      "expires_at": null,
      "topic": "FEATURES",
      "attachment_type": "link",
      "attachment_url": "https://example.com/features",
      "attachment_metadata": {
        "button_text": "Learn More"
      },
      "created_at": "2024-12-11T14:30:00Z",
      "is_read": true,
      "is_dismissed": false
    }
  ]
}

Notes

• Only returns announcements that are:
  • Status is published
  • Not scheduled in the future (scheduled_at is null or in the past)
  • Not expired (expires_at is null or in the future)
• Results are ordered by priority (high first) then by creation date (newest first)
• The is_read and is_dismissed fields are specific to the authenticated user
• Dismissed announcements are excluded from the results