Meta tags:
description= Things to keep in mind when implementing a Mastodon app.;
Headings (most frequently used words):
and, api, responses, side, filtering, mastodon, guidelines, best, practices, login, usernames, handling, ids, within, paginating, through, deprecations, formatting, filters, focal, points, for, cropping, media, thumbnails, sponsored, by, mentions, hashtags, custom, emoji, link, shortening, server, v2, above, client, v1, prior, to,
Text of the page (most frequently used words):
the (80), and (45), #mastodon (34), for (34), api (24), are (17), with (16), will (16), this (15), should (15), server (14), not (14), that (14), ids (13), admin (13), app (12), your (12), filter (11), statuses (11), matched (10), client (10), example (10), filters (9), page (8), can (8), from (8), character (8), they (8), may (8), status (8), span (8), you (8), using (8), link (8), results (8), their (7), class (7), following (7), entities (7), points (6), side (6), apps (6), word (6), next (6), still (6), text (6), filtering (6), than (6), profile (6), use (6), https (6), such (6), return (6), setting (6), responses (6), oauth (6), focal (5), user (5), must (5), see (5), range (5), reference (5), more (5), all (5), which (5), other (5), have (5), min_id (5), accounts (5), string (5), integers (5), account (5), within (4), previous (4), users (4), time (4), notifications (4), when (4), there (4), tags (4), mentions (4), entity (4), content (4), these (4), apis (4), header (4), http (4), max_id (4), methods (4), response (4), sets (4), since (4), limit (4), sort (4), search (4), instance (4), source (3), cropping (3), those (3), certain (3), always (3), center (3), would (3), thumbnails (3), media (3), javascript (3), index (3), its (3), treated (3), before (3), uses (3), but (3), clients (3), own (3), returned (3), filter_action (3), least (3), one (3), post (3), need (3), filtered (3), implementations (3), posts (3), doing (3), intended (3), url (3), very (3), long (3), ellipsis (3), invisible (3), links (3), hashtags (3), custom (3), plain (3), handling (3), html (3), deprecated (3), get (3), keep (3), some (3), endpoint (3), database (3), usually (3), parameters (3), since_id (3), effect (3), trends (3), implementing (3), guidelines (3), best (3), practices (3), preferences (3), reports (3), new (3), cropped (2), therefore (2), image (2), left (2), right (2), upper (2), quadrant (2), lower (2), guide (2), defined (2), lib (2), feed_manager (2), selectors (2), check (2), code (2), details (2), phrase (2), after (2), match (2), characters (2), official (2), ruby (2), longer (2), based (2), apply (2), irreversible (2), home (2), prior (2), values (2), warn (2), active (2), has (2), otherwise (2), hidden (2), able (2), context (2), public (2), however (2), rule (2), allow (2), attributes (2), filterresult (2), included (2), attribute (2), any (2), them (2), above (2), remain (2), instead (2), yourself (2), com (2), shortened (2), shorteners (2), like (2), shortening (2), emojis (2), tag (2), emoji (2), activitypub (2), sanitization (2), available (2), remote (2), vary (2), formatting (2), recommended (2), application (2), deprecations (2), case (2), information (2), relation (2), show (2), prev (2), rfc (2), rel (2), only (2), cursor (2), paginates (2), forward (2), many (2), greater (2), bound (2), maximum (2), number (2), paginating (2), through (2), generally (2), responsible (2), although (2), sorted (2), newer (2), vanilla (2), numbers (2), generation (2), algorithm (2), another (2), does (2), cast (2), errors (2), equal (2), username (2), domain (2), acct (2), usernames (2), scopes (2), logging (2), login (2), notificationpolicy (2), report (2), quote (2), domainblock (2), collections (2), domain_blocks (2), tokens (2), security (2), environment (2), machine (2), installing (2), features (2), configuring (2), running (2), imprint, view, blog, join, sponsored, last, updated, november, 2025, improve, demonstration, various, coordinates, preview, images, never, support, variety, interfaces, done, crop, intelligently, used, ensure, section, viewport, summary, floating, bottom, top, front, end, most, commonly, how, please, ends, starts, define, constituent, implementation, posix, letter, mark, decimal_number, connector_punctuation, true, whole_word, expired, deleted, applied, stored, update, expiry, enable, delete, eventually, wish, contexts, somehow, removed, anything, else, extension, purposes, unknown, shown, warning, reveal, being, informed, identified, rather, exact, keywords, title, hide, expiration, date, thread, want, perform, matching, retroactively, applying, changes, without, fetching, take, care, ignore, entries, handle, extensions, system, status_matches, keyword_matches, applies, corresponding, matches, action, spans, middle, visible, inserted, markup, expected, insert, href, usage, heavily, discouraged, urls, count, visually, purpose, marked, shortcode, form, give, semantic, meaning, add, special, opening, mentioned, web, metadata, particular, servers, syntax, rules, wildly, between, fediverse, applications, expect, appear, provides, sanitized, furthermore, help, implementers, spotting, makes, library, developers, look, display, warnings, development, environments, spot, retired, rfc9745, deprecation, rarely, removes, happen, releases, eye, out, retrieve, parse, parsing, headers, specifically, about, 8288, 9651, array, 7163058, 7275607, 200, authorization, bearer, access_token, host, operate, publicly, exposed, known, backend, follow, favourite, etc, around, prepopulated, consider, fictitious, call, oldest, latest, been, earlier, might, fetch, cases, returns, immediately, lesser, default, according, method, paginate, sorting, generating, reverse, chronological, order, insertion, into, relevance, lexically, digit, higher, compared, positionally, length, said, because, representations, chronologically, unofficial, guaranteed, numeric, lexical, forms, even, produce, 128, bit, encoded, base, alphabet, contain, letters, uris, represent, flake, generated, variant, older, internal, auto, incrementing, serializer, mean, nor, lead, broken, due, integer, overflow, related, casting, snowflake, treat, opaque, strings, possible, given, displaying, somewhere, note, local, decentralization, transparent, means, ask, registrations, dynamically, obtain, oauth2, credentials, log, things, mind, webpushsubscription, translation, token, termsofservice, suggestion, statussource, statusedit, shallowtag, shallowquote, scheduledstatus, role, relationshipseveranceevent, relationship, reaction, quoteapproval, privacypolicy, previewcardauthor, previewcard, poll, notificationrequest, notificationfallback, notification, mediaattachment, marker, list, identityproof, filterstatus, filterkeyword, featuredtag, featureapproval, familiarfollowers, extendeddescription, error, customemoji, conversation, collectionwithaccounts, collectionitem, collection, asyncrefresh, appeal, annualreport, announcement, measure, ipblock, emaildomainblock, domainallow, dimension, cohort, canonicalemailblock, accountwarning, streaming, markers, lists, conversations, timelines, scheduled_statuses, polls, proofs, oembed, push, directory, custom_emojis, announcements, health, grouped, async_refreshes, emails, annual, retention, measures, ip_blocks, email_domain_blocks, domain_allows, dimensions, canonical_email_blocks, suggestions, mutes, followed_tags, follow_requests, featured_tags, favourites, endorsements, bookmarks, blocks, rate, limits, datetime, formats, rest, bearcaps, microformats, webfinger, spec, compliance, design, creating, themes, css, styling, state, management, components, frontend, issues, disclosure, routes, structure, dev, technical, overview, contributing, libraries, obtaining, access, playing, data, getting, started, developing, roles, webhooks, corruption, troubleshooting, moderation, actions, scaling, migrating, backing, upgrading, release, cli, single, sign, captcha, onion, services, object, storage, optional, full, preparing, ios, android, moving, leaving, externally, settings, set, promoting, others, dealing, unwanted, quoting, network, posting, signing, what, documentation,
Text of the page (random words):
guidelines and best practices mastodon documentation what is mastodon using mastodon signing up for an account setting up your profile posting to your profile using the network features quoting other posts dealing with unwanted content promoting yourself and others set your preferences more settings using mastodon externally moving or leaving accounts official ios and android apps 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 webhooks 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 implementing quote posts implementing collections contributing to mastodon technical overview setting up a dev environment code structure routes security issues and responsible disclosure frontend guide components state management css and styling creating themes design tokens reference spec compliance activitypub webfinger security microformats oauth bearcaps rest api datetime formats guidelines and best practices oauth tokens oauth scopes rate limits api methods accounts blocks bookmarks domain_blocks endorsements favourites featured_tags filters follow_requests followed_tags mutes preferences reports suggestions tags admin accounts canonical_email_blocks dimensions domain_allows domain_blocks email_domain_blocks ip_blocks measures reports retention trends annual reports apps emails oauth async_refreshes collections grouped notifications health instance announcements custom_emojis directory trends notifications push oembed profile proofs search statuses media polls scheduled_statuses timelines conversations lists markers streaming 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 annualreport appeal application asyncrefresh collection collectionitem collectionwithaccounts context conversation customemoji domainblock error extendeddescription familiarfollowers featureapproval featuredtag filter filterkeyword filterresult filterstatus identityproof instance list marker mediaattachment notification notificationfallback notificationpolicy notificationrequest poll preferences previewcard previewcardauthor privacypolicy profile quote quoteapproval reaction relationship relationshipseveranceevent report role rule scheduledstatus search shallowquote shallowtag status statusedit statussource suggestion tag termsofservice token translation v1 filter v1 instance v1 notificationpolicy webpushsubscription guidelines and best practices things to keep in mind when implementing a mastodon app login usernames handling ids within api responses paginating through api responses deprecations formatting mentions hashtags and custom emoji link shortening filters server side filtering v2 mastodon 4 0 and above client side filtering v1 prior to mastodon 4 0 focal points for cropping media thumbnails login the user must be able to log in to any mastodon server from the app this means you must ask for the server s domain and use the app registrations api to dynamically obtain oauth2 credentials logging in with an account oauth methods oauth scopes usernames decentralization must be transparent to the user it should be possible to see that a given user is from another server for example by displaying their acct somewhere note that acct is equal to username for local users and equal to username domain for remote users handling ids within api responses always treat ids as opaque strings vanilla mastodon entity ids are generated as integers usually using a variant of snowflake id although older ids or ids for internal use only may be auto incrementing integers and the api response serializer will cast them to string however this does not mean that ids are integers nor should they be cast to integers doing so can lead to broken client apps due to integer overflow or other errors related to casting unofficial implementations of the mastodon api are not guaranteed to use numeric lexical forms or even numbers at all for example an id generation algorithm like flake will produce 128 bit integers encoded using a base 62 alphabet so such ids will contain letters as another example an id generation algorithm that uses https uris does not represent a number at all with that said because vanilla mastodon uses ids that are string representations of numbers they can still be sorted chronologically by doing the following sort by length newer statuses will have longer ids sort lexically newer statuses will have at least one digit that is higher when compared positionally clients generally do not need to sort ids the server is responsible for sorting ids before generating the api response mastodon will generally sort api responses in reverse chronological order by time of insertion into its database although some api responses may be sorted by relevance such as search results or trends paginating through api responses many api methods allow you to paginate for more information using parameters such as limit max_id min_id and since_id limit the maximum number of results to return usually there is a default limit and a maximum limit these will vary according to the api method max_id string all results returned will be lesser than this id in effect sets an upper bound on results since_id string all results returned will be greater than this id in effect sets a lower bound on results min_id string returns results immediately greater than this id in effect sets a cursor at this id and paginates forward available since v2 6 0 for example a client might fetch https mastodon example api v1 accounts 1 statuses with certain parameters and mastodon will return the following results in the following cases setting max_id 1 will return no statuses since there are no statuses with an id earlier than 1 setting since_id 1 will return the latest statuses since there have been many statuses since 1 setting min_id 1 will return the oldest statuses as min_id sets the cursor at 1 and paginates forward some api methods operate on entity ids that are not publicly exposed in the api response and are only known to the backend and the database this is usually the case for entities that reference other entities such as follow entities which reference accounts or favourite entities which reference statuses etc to get around this mastodon may return links to a next and or previous page with prepopulated values for these parameters consider the following fictitious api call and response get api v1 endpoint http 1 1 host mastodon example authorization bearer access_token http 1 1 200 ok link https mastodon example api v1 endpoint max_id 7163058 rel next https mastodon example api v1 endpoint min_id 7275607 rel prev some entity more entities in an array in this case you can retrieve the http link header and parse it for links to the next or previous page see rfc 9651 for parsing http headers and see rfc 8288 for information specifically about the link header following the next link relation should show you the next page following the prev link relation should show you the previous page deprecations mastodon rarely removes apis but that can still happen from time to time therefore it is recommended to keep up with mastodon releases and keep an eye out for deprecated apis furthermore to help implementers with spotting use of deprecated apis mastodon 4 4 0 makes use of the deprecation header defined in rfc9745 it is recommended that library and application developers look for this header and display warnings in their development environments so they can spot these deprecated apis before they get retired formatting plain text is not available for content from remote servers and plain text syntax rules may vary wildly between mastodon and other fediverse applications for certain attributes such as the content of statuses mastodon provides sanitized html see html sanitization for more details you may expect these tags to appear in the content p br span a activitypub html sanitization mentions hashtags and custom emoji mentions and hashtags are a tags custom emojis remain in their plain text shortcode form to give those entities their semantic meaning and add special handling such as opening a mentioned profile within your app instead of as a web page metadata is included with the status which can be matched to a particular tag status entity status mentions status tags status emojis link shortening links in mastodon are not shortened using url shorteners and the usage of url shorteners is heavily discouraged urls in text always count for 23 characters and are intended to be shortened visually for that purpose a link is marked up like this a href https example com page that is very long span class invisible https span span class ellipsis example com page span span class invisible that is very long span a the spans with the invisible class can be hidden the middle span is intended to remain visible it may have no class if the url is not very long otherwise it will have an ellipsis class no ellipsis character is inserted in the markup instead you are expected to insert it yourself if you need it in your app filters server side filtering v2 mastodon 4 0 and above if a filter applies to a status a corresponding filterresult will be included in the filtered attribute clients should check this attribute for any matches and use them to apply the intended filter action however client implementations may still want to perform their own rule matching client side as this would allow retroactively applying filter changes without re fetching posts from the server when doing so they should take care to not ignore filtered entries for which there are other attributes than keyword_matches so as to handle extensions of the filtering system e g status_matches matched filters need to be filtered based on context home notifications public thread or profile and expiration date when at least one active matched filter has hide for filter_action the post should not be shown at all otherwise if at least one active matched filter has warn for filter_action the post should be hidden with a warning and the user should be able to reveal the post after being informed of which filters matched identified by title rather than the exact matched keywords for extension purposes unknown values for filter_action should be treated as warn client side filtering v1 prior to mastodon 4 0 clients must do their own text filtering based on filters returned from the api the server will apply irreversible filters for home and notifications contexts but anything else is still up to the client to filter if a status is somehow not removed by an irreversible filter the client should still filter it expired filters are not deleted by the server they should no longer be applied but they are still stored by the server as users may update the expiry time to re enable the filter it is up to users to delete those filters eventually if they wish to do so if whole_word is true the client app should do the following define word constituent characters for your app in the official implementation it s a za z0 9_ in javascript and word in ruby ruby uses the posix character class letter mark decimal_number connector_punctuation if the phrase starts with a word character and if the previous character before the matched range is a word character its matched range should be treated to not match if the phrase ends with a word character and if the next character after the matched range is a word character its matched range should be treated to not match please check app javascript mastodon selectors index js and app lib feed_manager rb in the mastodon source code for more details app javascript mastodon selectors index js app lib feed_manager rb focal points for cropping media thumbnails server side preview images are never cropped to support a variety of apps and user interfaces therefore the cropping must be done by those apps to crop intelligently focal points can be used to ensure a certain section of the image is always within the cropped viewport see this guide on how focal points are defined in summary floating points range from 1 0 to 1 0 left to right or bottom to top 0 0 is the center of the image 0 5 0 5 would be in the center of the upper right quadrant 0 5 0 5 would be in the center of the lower left quadrant for reference thumbnails in the mastodon front end are most commonly 16 9 a demonstration of various focal points and their coordinates last updated november 23 2025 improve this page sponsored by join mastodon blog view source cc by sa 4 0 imprint
|
