Meta tags:
description= A primer on REST APIs, HTTP requests and responses, and parameters.;
Headings (most frequently used words):
data, api, to, parameters, getting, started, with, the, an, introduction, rest, understanding, http, requests, and, responses, providing, types, how, use, response, sponsored, by, query, strings, form, json, multiple, values, array, nested, hash, true, or, false, booleans, files,
Text of the page (most frequently used words):
the (41), data (25), for (20), and (19), mastodon (18), with (18), json (16), api (15), http (13), admin (13), #strings (12), request (11), your (11), form (11), curl (11), query (11), example (10), may (9), requests (9), rest (9), can (8), using (8), post (8), you (7), parameters (7), array (7), send (7), source (6), server (6), use (6), false (6), https (6), endpoint (6), response (5), also (5), value (5), used (5), but (5), this (4), content (4), will (4), which (4), values (4), true (4), language (4), public (4), are (4), that (4), multiple (4), test (4), flag (4), get (4), instance (4), profile (4), account (4), oauth (4), error (3), most (3), not (3), status (3), how (3), following (3), must (3), encoded (3), multipart (3), files (3), considered (3), other (3), instead (3), privacy (3), nested (3), notation (3), bar (3), foo (3), parameter (3), type (3), sending (3), additional (3), specify (3), separately (3), utility (3), resource (3), methods (3), responses (3), its (3), getting (3), started (3), search (3), preferences (3), apps (3), reports (3), accounts (3), setting (3), new (3), view (2), page (2), handling (2), commonly (2), see (2), client (2), was (2), 404 (2), many (2), handled (2), text (2), headers (2), well (2), code (2), expected (2), arrays (2), file (2), all (2), off (2), booleans (2), formatted (2), like (2), bracket (2), would (2), translated (2), into (2), hash (2), types (2), application (2), similar (2), header (2), then (2), one (2), overview (2), object (2), allows (2), raw (2), url (2), sent (2), key (2), pairs (2), appended (2), them (2), include (2), various (2), providing (2), default (2), method (2), make (2), purposes (2), information (2), more (2), understanding (2), access (2), state (2), introduction (2), notificationpolicy (2), filter (2), report (2), quote (2), domainblock (2), notifications (2), trends (2), collections (2), domain_blocks (2), tokens (2), security (2), environment (2), implementing (2), posts (2), machine (2), installing (2), features (2), configuring (2), running (2), imprint, blog, join, sponsored, last, updated, june, 2025, improve, 5xx, something, went, wrong, while, 503, unavailable, 4xx, correct, 401, unauthorized, found, 410, gone, 422, unprocessable, 429, too, 200, successfully, return, returns, useful, should, let, know, codes, combined, uploads, boolean, provided, empty, when, literals, null, hashes, some, need, format, defined, ecma, quick, www, org, javascript, filename, jpg, explicit, mutating, done, passing, together, flags, such, append, end, first, typing, appending, separating, submitted, via, body, equally, understood, different, ways, notably, understands, want, returned, part, where, relevant, favorite, programming, probably, has, library, section, examples, command, line, included, operating, systems, removes, delete, update, patch, put, read, endpoints, called, certain, than, same, generally, provides, over, stands, representational, transfer, our, just, think, receiving, about, resources, based, uses, payloads, primer, apis, webpushsubscription, translation, token, termsofservice, tag, suggestion, statussource, statusedit, shallowtag, shallowquote, scheduledstatus, rule, role, relationshipseveranceevent, relationship, reaction, quoteapproval, privacypolicy, previewcardauthor, previewcard, poll, notificationrequest, notificationfallback, notification, mediaattachment, marker, list, identityproof, filterstatus, filterresult, filterkeyword, featuredtag, featureapproval, familiarfollowers, extendeddescription, customemoji, conversation, context, collectionwithaccounts, collectionitem, collection, asyncrefresh, appeal, annualreport, announcement, measure, ipblock, emaildomainblock, domainallow, dimension, cohort, canonicalemailblock, accountwarning, entities, streaming, markers, lists, conversations, timelines, scheduled_statuses, polls, media, statuses, 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, tags, suggestions, mutes, followed_tags, follow_requests, filters, featured_tags, favourites, endorsements, bookmarks, blocks, rate, limits, scopes, guidelines, best, practices, datetime, formats, bearcaps, microformats, webfinger, activitypub, spec, compliance, design, reference, creating, themes, css, styling, management, components, frontend, guide, issues, responsible, disclosure, routes, structure, dev, technical, contributing, libraries, implementations, logging, obtaining, app, playing, developing, roles, webhooks, database, index, corruption, troubleshooting, errors, moderation, actions, scaling, migrating, backing, upgrading, release, cli, single, sign, captcha, onion, services, storage, optional, full, from, preparing, own, official, ios, android, moving, leaving, externally, settings, set, promoting, yourself, others, dealing, unwanted, quoting, network, posting, signing, what, documentation,
Text of the page (random words):
getting started with the api 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 getting started with the api a primer on rest apis http requests and responses and parameters an introduction to rest understanding http requests and responses providing parameters query strings form data json data types multiple values array nested parameters hash true or false booleans files how to use api response data an introduction to rest mastodon provides access to its data over a rest api rest stands for representational state transfer but for our purposes just think of it as sending and receiving information about various resources based on the request the mastodon rest api uses http for its requests and json for its payloads understanding http requests and responses rest api endpoints can be called with certain http methods and more than one method can be used on the same endpoint the mastodon api will generally use the following http methods get read or view a resource post send information to the server put patch update a resource delete removes a resource your favorite programming language probably has a utility or library to make http requests for the purposes of this section the curl utility will be used for examples which is a command line utility included with many operating systems by default as curl with curl the default http method is get but you can specify the type of request to make by using the request or x flag for example curl x post will send a post request instead of a get request you may also want to use the i flag to include additional http headers that may be returned as part of the response where relevant providing parameters http requests can include additional parameters in various different ways but most notably the mastodon api understands query strings form data and json query strings form data and json submitted via post body are equally understood by the api it is expected that query strings are used for get requests and form data or json is used for all other requests query strings request the url but append query strings to the end query strings can be appended by first typing and then appending them in the form of parameter value multiple query strings can be appended by separating them with for example curl https mastodon example endpoint q test n 0 form data instead of mutating the url with query strings you can send the data separately with curl this is done by passing it with the data or d flag data may be sent together similar to query strings or it may be sent separately as key value pairs with multiple data flags you may also use the form or f flag for key value pairs which also allows sending multipart data such as files for example send raw data as query strings curl x post d q test n 0 https mastodon example endpoint send raw data separately curl x post d q test d n 0 https mastodon example endpoint explicit form encoded allows for multipart data curl x post f q test f n 0 f file filename jpg https mastodon example endpoint json javascript object notation as defined in ecma 404 quick one page overview https www json org similar to sending form data but with an additional header to specify that the data is in json format to send a json request with curl specify the json content type with a header then send the json data as form data curl x post h content type application json d parameter value https mastodon example endpoint data types multiple values array an array parameter must be encoded using bracket notation for example array foo array bar would be translated into the following array foo bar as json arrays are formatted like so array foo bar nested parameters hash some parameters need to be nested for that bracket notation must also be used for example source privacy public source language en would be translated into source privacy public language en as json hashes are formatted like so source privacy public language en true or false booleans a boolean value is considered false for the values 0 f f false false off off considered to not be provided for empty strings and considered to be true for all other values when using json data use the literals true false and null instead files file uploads must be encoded using multipart form data this can be combined with arrays as well how to use api response data the mastodon rest api will return json as the response text it also returns http headers which may be useful in handling the response as well as an http status code which should let you know how the server handled the request the following http status codes may be expected 200 ok the request was handled successfully 4xx client error your request was not correct most commonly you may see 401 unauthorized 404 not found 410 gone 422 unprocessable content or 429 too many requests 5xx server error something went wrong while handling the request most commonly you may see 503 unavailable last updated june 25 2025 improve this page sponsored by join mastodon blog view source cc by sa 4 0 imprint
|
