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

Instance

Represents the software instance of Mastodon running on this domain.

    • Example
    • Attributes
      • domain
      • title
      • version
      • source_url
      • description
      • usage
      • thumbnail
      • icon
      • languages
      • configuration
      • registrations
      • api_versions
      • api_versions[mastodon]
      • contact
      • rules
    • InstanceIcon attributes
      • src
      • size
    • See also

Example

{
  "domain": "mastodon.social",
  "title": "Mastodon",
  "version": "4.4.0-alpha.3",
  "source_url": "https://github.com/mastodon/mastodon",
  "description": "The original server operated by the Mastodon gGmbH non-profit",
  "usage": {
    "users": {
      "active_month": 123122
    }
  },
  "thumbnail": {
    "url": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png",
    "blurhash": "UeKUpFxuo~R%0nW;WCnhF6RjaJt757oJodS$",
    "versions": {
      "@1x": "https://files.mastodon.social/site_uploads/files/000/000/001/@1x/57c12f441d083cde.png",
      "@2x": "https://files.mastodon.social/site_uploads/files/000/000/001/@2x/57c12f441d083cde.png"
    }
  },
  "icon": [
    {
      "src": "https://files.mastodon.social/site_uploads/files/000/000/003/36/accf17b0104f18e5.png",
      "size": "36x36"
    },
    {
      "src": "https://files.mastodon.social/site_uploads/files/000/000/003/72/accf17b0104f18e5.png",
      "size": "72x72"
    },
    {
      "src": "https://files.mastodon.social/site_uploads/files/000/000/003/192/accf17b0104f18e5.png",
      "size": "192x192"
    },
    {
      "src": "https://files.mastodon.social/site_uploads/files/000/000/003/512/accf17b0104f18e5.png",
      "size": "512x512"
    }
  ],
  "languages": [
    "en"
  ],
  "configuration": {
    "urls": {
      "streaming": "wss://mastodon.social",
      "about": "https://mastodon.social/about",
      "privacy_policy": "https://mastodon.social/privacy-policy",
      "terms_of_service": "https://mastodon.social/terms-of-service"
    },
    "vapid": {
      "public_key": "BCkMmVdKDnKYwzVCDC99Iuc9GvId-x7-kKtuHnLgfF98ENiZp_aj-UNthbCdI70DqN1zUVis-x0Wrot2sBagkMc="
    },
    "accounts": {
      "max_featured_tags": 10,
      "max_pinned_statuses": 4
    },
    "statuses": {
      "max_characters": 500,
      "max_media_attachments": 4,
      "characters_reserved_per_url": 23
    },
    "media_attachments": {
      "supported_mime_types": [
        "image/jpeg",
        "image/png",
        "image/gif",
        "image/heic",
        "image/heif",
        "image/webp",
        "video/webm",
        "video/mp4",
        "video/quicktime",
        "video/ogg",
        "audio/wave",
        "audio/wav",
        "audio/x-wav",
        "audio/x-pn-wave",
        "audio/vnd.wave",
        "audio/ogg",
        "audio/vorbis",
        "audio/mpeg",
        "audio/mp3",
        "audio/webm",
        "audio/flac",
        "audio/aac",
        "audio/m4a",
        "audio/x-m4a",
        "audio/mp4",
        "audio/3gpp",
        "video/x-ms-asf"
      ],
      "description_limit": 1500,
      "image_size_limit": 10485760,
      "image_matrix_limit": 16777216,
      "video_size_limit": 41943040,
      "video_frame_rate_limit": 60,
      "video_matrix_limit": 2304000
    },
    "polls": {
      "max_options": 4,
      "max_characters_per_option": 50,
      "min_expiration": 300,
      "max_expiration": 2629746
    },
    "translation": {
      "enabled": true
    }
  },
  "registrations": {
    "enabled": false,
    "approval_required": false,
    "reason_required": false,
    "message": null,
    "min_age": 16
  },
  "api_versions": {
    "mastodon": 1,
  },
  "contact": {
    "email": "staff@mastodon.social",
    "account": {
      "id": "1",
      "username": "Gargron",
      "acct": "Gargron",
      "display_name": "Eugen 馃拃",
      "locked": false,
      "bot": false,
      "discoverable": true,
      "group": false,
      "created_at": "2016-03-16T00:00:00.000Z",
      "note": "<p>Founder, CEO and lead developer <span class=\"h-card\"><a href=\"https://mastodon.social/@Mastodon\" class=\"u-url mention\">@<span>Mastodon</span></a></span>, Germany.</p>",
      "url": "https://mastodon.social/@Gargron",
      "avatar": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
      "avatar_static": "https://files.mastodon.social/accounts/avatars/000/000/001/original/dc4286ceb8fab734.jpg",
      "header": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
      "header_static": "https://files.mastodon.social/accounts/headers/000/000/001/original/3b91c9965d00888b.jpeg",
      "followers_count": 133026,
      "following_count": 311,
      "statuses_count": 72605,
      "last_status_at": "2022-10-31",
      "noindex": false,
      "emojis": [],
      "fields": [
        {
          "name": "Patreon",
          "value": "<a href=\"https://www.patreon.com/mastodon\" target=\"_blank\" rel=\"nofollow noopener noreferrer me\"><span class=\"invisible\">https://www.</span><span class=\"\">patreon.com/mastodon</span><span class=\"invisible\"></span></a>",
          "verified_at": null
        }
      ]
    }
  },
  "rules": [
    {
      "id": "1",
      "text": "Sexually explicit or violent media must be marked as sensitive when posting"
    },
    {
      "id": "2",
      "text": "No racism, sexism, homophobia, transphobia, xenophobia, or casteism"
    },
    {
      "id": "3",
      "text": "No incitement of violence or promotion of violent ideologies"
    },
    {
      "id": "4",
      "text": "No harassment, dogpiling or doxxing of other users"
    },
    {
      "id": "5",
      "text": "No content illegal in Germany"
    },
    {
      "id": "7",
      "text": "Do not share intentionally false or misleading information"
    }
  ]
}

Attributes

domain

Description: The WebFinger domain name of the instance.
Type: String
Version history:
4.0.0 - added

title

Description: The title of the website.
Type: String
Version history:
4.0.0 - added

version

Description: The version of Mastodon installed on the instance.
Type: String
Version history:
4.0.0 - added

source_url

Description: The URL for the source code of the software running on this instance, in keeping with AGPL license requirements.
Type: String (URL)
Version history:
4.0.0 - added

description

Description: A short, plain-text description defined by the admin.
Type: String
Version history:
4.0.0 - added

usage

Description: Usage data for this instance.
Type: Hash
Version history:
4.0.0 - added

usage[users]

Description: Usage data related to users on this instance.
Type: Hash
Version history:
4.0.0 - added

usage[users][active_month]

Description: The number of active users in the past 4 weeks. This is set to zero for servers with configuration[limited_federation].
Type: Integer
Version history:
4.0.0 - added

thumbnail

Description: An image used to represent this instance.
Type: Hash
Version history:
4.0.0 - added

thumbnail[url]

Description: The URL for the thumbnail image.
Type: String (URL)
Version history:
4.0.0 - added

thumbnail[blurhash] optional

Description: A hash computed by the BlurHash algorithm, for generating colorful preview thumbnails when media has not been downloaded yet.
Type: String (Blurhash)
Version history:
4.0.0 - added

thumbnail[versions] optional

Description: Links to scaled resolution images, for high DPI screens.
Type: Hash
Version history:
4.0.0 - added

thumbnail[versions][@1x] optional

Description: The URL for the thumbnail image at 1x resolution.
Type: String (URL)
Version history:
4.0.0 - added

thumbnail[versions][@2x] optional

Description: The URL for the thumbnail image at 2x resolution.
Type: String (URL)
Version history:
4.0.0 - added

icon

Description: The list of available size variants for this instance configured icon.
Type: Array of InstanceIcon
Version history:
4.3.0 - added

languages

Description: Primary languages of the website and its staff.
Type: Array of String (ISO 639-1 two-letter code)
Version history:
4.0.0 - added

configuration

Description: Configured values and limits for this website.
Type: Hash
Version history:
4.0.0 - added

configuration[urls]

Description: URLs of interest for clients apps.
Type: Hash
Version history:
4.0.0 - added

configuration[urls][streaming]

Description: The Websockets URL for connecting to the streaming API.
Type: String (URL)
Version history:
4.0.0 - added

configuration[urls][about]

Description: The URL of the server’s about page.
Type: String (URL)
Version history:
4.4.0 - added

configuration[urls][privacy_policy]

Description: The URL of the server’s privacy policy.
Type: String (URL) or null
Version history:
4.4.0 - added

configuration[urls][terms_of_service]

Description: The URL of the server’s current terms of service, if any.
Type: nullable String (URL)
Version history:
4.4.0 - added

configuration[vapid][public_key]

Description: The instances VAPID public key, used for push notifications, the same as WebPushSubscription#server_key.
Type: String
Version history:
4.3.0 - added

configuration[accounts]

Description: Limits related to accounts.
Type: Hash
Version history:
4.0.0 - added

configuration[accounts][max_featured_tags]

Description: The maximum number of featured tags allowed for each account.
Type: Integer
Version history:
4.0.0 - added

configuration[accounts][max_pinned_statuses]

Description: The maximum number of pinned statuses for each account.
Type: Integer
Version history:
4.3.0 - added

configuration[statuses]

Description: Limits related to authoring statuses.
Type: Hash
Version history:
4.0.0 - added

configuration[statuses][max_characters]

Description: The maximum number of allowed characters per status.
Type: Integer
Version history:
4.0.0 - added

configuration[statuses][max_media_attachments]

Description: The maximum number of media attachments that can be added to a status.
Type: Integer
Version history:
4.0.0 - added

configuration[statuses][characters_reserved_per_url]

Description: Each URL in a status will be assumed to be exactly this many characters.
Type: Integer
Version history:
4.0.0 - added

configuration[media_attachments]

Description: Hints for which attachments will be accepted.
Type: Hash
Version history:
4.0.0 - added

configuration[media_attachments][supported_mime_types]

Description: Contains MIME types that can be uploaded.
Type: Array of String
Version history:
4.0.0 - added

configuration[media_attachments][description_limit]

Description: The maximum size of a description, in characters.
Type: Integer
Version history:
4.4.0 - added

configuration[media_attachments][image_size_limit]

Description: The maximum size of any uploaded image, in bytes.
Type: Integer
Version history:
4.0.0 - added

configuration[media_attachments][image_matrix_limit]

Description: The maximum number of pixels (width times height) for image uploads.
Type: Integer
Version history:
4.0.0 - added

configuration[media_attachments][video_size_limit]

Description: The maximum size of any uploaded video, in bytes.
Type: Integer
Version history:
4.0.0 - added

configuration[media_attachments][video_frame_rate_limit]

Description: The maximum frame rate for any uploaded video.
Type: Integer
Version history:
4.0.0 - added

configuration[media_attachments][video_matrix_limit]

Description: The maximum number of pixels (width times height) for video uploads.
Type: Integer
Version history:
4.0.0 - added

configuration[polls]

Description: Limits related to polls.
Type: Hash
Version history:
4.0.0 - added

configuration[polls][max_options]

Description: Each poll is allowed to have up to this many options.
Type: Integer
Version history:
4.0.0 - added

configuration[polls][max_characters_per_option]

Description: Each poll option is allowed to have this many characters.
Type: Integer
Version history:
4.0.0 - added

configuration[polls][min_expiration]

Description: The shortest allowed poll duration, in seconds.
Type: Integer
Version history:
4.0.0 - added

configuration[polls][max_expiration]

Description: The longest allowed poll duration, in seconds.
Type: Integer
Version history:
4.0.0 - added

configuration[translation]

Description: Hints related to translation.
Type: Hash
Version history:
4.0.0 - added

configuration[translation][enabled]

Description: Whether the Translations API is available on this instance.
Type: Boolean
Version history:
4.0.0 - added

configuration[limited_federation]

Description: Whether federation is limited to explicitly allowed domains.
Type: Boolean
Version history:
4.4.0 - added

registrations

Description: Information about registering for this website.
Type: Hash
Version history:
4.0.0 - added

registrations[enabled]

Description: Whether registrations are enabled.
Type: Boolean
Version history:
4.0.0 - added

registrations[approval_required]

Description: Whether registrations require moderator approval.
Type: Boolean
Version history:
4.0.0 - added

registrations[message]

Description: A custom message to be shown when registrations are closed.
Type: nullable String (HTML) or null
Version history:
4.0.0 - added

registrations[min_age]

Description: A minimum age required to register, if configured.
Type: nullable Integer or null
Version history:
4.4.0 - added

registrations[reason_required]

Description: Whether registrations require the user to provide a reason for joining. Only applicable when registrations[approval_required] is true.
Type: nullable Boolean
Version history:
4.4.0 - added

api_versions

Description: Information about which version of the API is implemented by this server. It contains at least a mastodon attribute, and other implementations may have their own additional attributes.
Type: Hash
Version history:
4.3.0 - added

api_versions[mastodon]

Description: API version number that this server implements. Starting from Mastodon v4.3.0, API changes will come with a version number, which clients can check against this value.
Type: Integer
Version history:
4.3.0 - added

contact

Description: Hints related to contacting a representative of the website.
Type: Hash
Version history:
4.0.0 - added

contact[email]

Description: An email address that can be messaged regarding inquiries or issues.
Type: String (Email)
Version history:
4.0.0 - added

contact[account]

Description: An account that can be contacted natively over the network regarding inquiries or issues.
Type: nullable Account or null
Version history:
4.0.0 - added

rules

Description: An itemized list of rules for this website.
Type: Array of Rule
Version history:
4.0.0 - added

InstanceIcon attributes

src

Description: The URL of this icon.
Type: String
4.3.0 - added

size

Description: The size of this icon.
Type: String (in the form of 12x34, where 12 is the width and 34 is the height of the icon)
Version history:
4.3.0 - added

See also

GET /api/v2/instance
app/serializers/rest/instance_serializer.rb

Last updated May 13, 2025 路 Improve this page

Sponsored by

Dotcom-Monitor LoadView Stephen Tures Swayable SponsorMotion

Join Mastodon 路 Blog 路

View source 路 CC BY-SA 4.0 路 Imprint