Mastodon
  • What is Mastodon?
  • Using Mastodon
    • Signing up for an account
    • Setting up your profile
    • Posting to your profile
    • Using the network features
    • Dealing with unwanted content
    • Promoting yourself and others
    • Set your preferences
    • More settings
    • Using Mastodon externally
    • Moving or leaving accounts
    • Running your own server
  • Running Mastodon
    • Preparing your machine
    • Installing from source
    • Configuring your environment
    • Configuring full-text search
    • Installing optional features
      • Object storage
      • Onion services
      • Captcha
      • Single Sign On
    • Setting up your new instance
    • Using the admin CLI
    • Upgrading to a new release
    • Backing up your server
    • Migrating to a new machine
    • Scaling up your server
    • Moderation actions
    • Troubleshooting errors
      • Database index corruption
    • Roles
  • Developing Mastodon apps
    • Getting started with the API
    • Playing with public data
    • Obtaining client app access
    • Logging in with an account
    • Libraries and implementations
  • Contributing to Mastodon
    • Technical overview
    • Setting up a dev environment
    • Code structure
    • Routes
    • Bug bounties and responsible disclosure
  • Spec compliance
    • ActivityPub
    • WebFinger
    • Security
    • Microformats
    • OAuth
    • Bearcaps
  • REST API
    • Datetime formats
    • Guidelines and best practices
    • OAuth Tokens
    • OAuth Scopes
    • Rate limits
  • API Methods
    • apps
      • oauth
      • emails
    • accounts
      • bookmarks
      • favourites
      • mutes
      • blocks
      • domain_blocks
      • filters
      • reports
      • follow_requests
      • endorsements
      • featured_tags
      • preferences
      • followed_tags
      • suggestions
      • tags
    • profile
    • statuses
      • media
      • polls
      • scheduled_statuses
    • timelines
      • conversations
      • lists
      • markers
      • streaming
    • grouped notifications
    • notifications
      • push
    • search
    • instance
      • trends
      • directory
      • custom_emojis
      • announcements
    • admin
      • accounts
      • canonical_email_blocks
      • dimensions
      • domain_allows
      • domain_blocks
      • email_domain_blocks
      • ip_blocks
      • measures
      • reports
      • retention
      • trends
    • proofs
    • oembed
  • API Entities
    • Account
    • AccountWarning
    • Admin::Account
    • Admin::CanonicalEmailBlock
    • Admin::Cohort
    • Admin::Dimension
    • Admin::DomainAllow
    • Admin::DomainBlock
    • Admin::EmailDomainBlock
    • Admin::Ip
    • Admin::IpBlock
    • Admin::Measure
    • Admin::Report
    • Announcement
    • Appeal
    • Application
    • Context
    • Conversation
    • CustomEmoji
    • DomainBlock
    • Error
    • ExtendedDescription
    • FamiliarFollowers
    • FeaturedTag
    • Filter
    • FilterKeyword
    • FilterResult
    • FilterStatus
    • IdentityProof
    • Instance
    • List
    • Marker
    • MediaAttachment
    • Notification
    • NotificationPolicy
    • NotificationRequest
    • Poll
    • Preferences
    • PreviewCard
    • PreviewCardAuthor
    • PrivacyPolicy
    • Quote
    • Reaction
    • Relationship
    • RelationshipSeveranceEvent
    • Report
    • Role
    • Rule
    • ScheduledStatus
    • Search
    • ShallowQuote
    • Status
    • StatusEdit
    • StatusSource
    • Suggestion
    • Tag
    • TermsOfService
    • Token
    • Translation
    • V1::Filter
    • V1::Instance
    • V1::NotificationPolicy
    • WebPushSubscription

announcements API methods

For announcements set by administration.

    • View all announcements
    • Dismiss an announcement
    • Add a reaction to an announcement
    • Remove a reaction from an announcement
    • See also

View all announcements

GET /api/v1/announcements HTTP/1.1

See all currently active announcements set by admins.

Returns: Array of Announcement
OAuth: User token
Version history:
3.1.0 - added

Request

Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK

Currently active announcements

[
  {
    "id": "8",
    "content": "<p>Looks like there was an issue processing audio attachments without embedded art since yesterday due to an experimental new feature. That issue has now been fixed, so you may see older posts with audio from other servers pop up in your feeds now as they are being finally properly processed. Sorry!</p>",
    "starts_at": null,
    "ends_at": null,
    "all_day": false,
    "published_at": "2020-07-03T01:27:38.726Z",
    "updated_at": "2020-07-03T01:27:38.752Z",
    "read": true,
    "mentions": [],
    "statuses": [],
    "tags": [],
    "emojis": [],
    "reactions": [
      {
        "name": "bongoCat",
        "count": 9,
        "me": false,
        "url": "https://files.mastodon.social/custom_emojis/images/000/067/715/original/fdba57dff7576d53.png",
        "static_url": "https://files.mastodon.social/custom_emojis/images/000/067/715/static/fdba57dff7576d53.png"
      },
      {
        "name": "thonking",
        "count": 1,
        "me": false,
        "url": "https://files.mastodon.social/custom_emojis/images/000/098/690/original/a8d36edc4a7032e8.png",
        "static_url": "https://files.mastodon.social/custom_emojis/images/000/098/690/static/a8d36edc4a7032e8.png"
      },
      {
        "name": "AAAAAA",
        "count": 1,
        "me": false,
        "url": "https://files.mastodon.social/custom_emojis/images/000/071/387/original/AAAAAA.png",
        "static_url": "https://files.mastodon.social/custom_emojis/images/000/071/387/static/AAAAAA.png"
      },
      {
        "name": "馃",
        "count": 1,
        "me": true
      }
    ]
  }
]
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}

Dismiss an announcement

POST /api/v1/announcements/:id/dismiss HTTP/1.1

Allows a user to mark the announcement as read.

Returns: Empty
OAuth: User token + write:accounts
Version history:
3.1.0 - added

Request

Path parameters
:id
required String. The ID of the Announcement in the database.
Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK
{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Announcement with given ID does not exist

{
  "error": "Record not found"
}

Add a reaction to an announcement

PUT /api/v1/announcements/:id/reactions/:name HTTP/1.1

React to an announcement with an emoji.

Returns: Empty
OAuth: User token + write:favourites
Version history:
3.1.0 - added

Request

Path parameters
:id
required String. The ID of the Announcement in the database.
:name
required String. Unicode emoji, or the shortcode of a custom emoji.
Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK
{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Announcement with given ID does not exist

{
  "error": "Record not found"
}
422: Unprocessable entity
{
  "error": "Validation failed: Name is not a recognized emoji"
}

Remove a reaction from an announcement

DELETE /api/v1/announcements/:id/reactions/:name HTTP/1.1

Undo a react emoji to an announcement.

Returns: Empty
OAuth: User token + write:favourites
Version history:
3.1.0 - added

Request

Path parameters
:id
required String. The ID of the Announcement in the database.
:name
required String. Unicode emoji, or the shortcode of a custom emoji.
Headers
Authorization
required Provide this header with Bearer <user_token> to gain authorized access to this API method.

Response

200: OK
{}
401: Unauthorized

Invalid or missing Authorization header.

{
  "error": "The access token is invalid"
}
404: Not found

Announcement with given ID does not exist

{
  "error": "Record not found"
}
422: Unprocessable entity
{
  "error": "Validation failed: Name is not a recognized emoji"
}

See also

app/controllers/api/v1/announcements_controller.rb
app/controllers/api/v1/announcements/reactions_controller.rb

Last updated October 10, 2024 路 Improve this page

Sponsored by

Dotcom-Monitor LoadView Stephen Tures Swayable SponsorMotion

Join Mastodon 路 Blog 路

View source 路 CC BY-SA 4.0 路 Imprint