Documentation » API » Making API requests

To call an API method, make a GET or POST request to:

https://<server address>/api/method/:method_name

Parameters can be passed either as query parameters or, in case of POST requests, as form data in the request body.

In addition to parameters specific to each method, there are global parameters applicable to all methods:

  • v is the only required parameter specifying the API version to use, as major.minor. Currently, the only version is 1.0.
  • access_token is the access token for performing actions on behalf of a user. Alternatively, can be passed as a header Authorization: Bearer <token>.
  • lang is a language code like en-GB or ru for methods that use translatable strings or inflect people’s names.
  • image_format specifies in which format you would like images to be returned. Possible values are webp (default) and jpeg.

Each request returns a JSON object, containing the response property in case of a successful response or error in case of an error.

Object IDs and decentralization

As Smithereen is part of a decentralized network, it is important that you handle object IDs correctly.

If you share objects across servers, for example:

  • Your app is a client that allows adding multiple accounts and picking which account to open a post with
  • Your app is a game where you keep a global scoreboard
  • Your app is a dating app where you show your users other users’ profiles

…you need to use ap_id instead of id.

id, for any object, be that a user or a piece of content like a post or a photo, is derived form the database row ID on the server you’re communicating with, and so is only unique within that server; different servers will assign different ids to the same object. ap_id, on the other hand, is the ActivityPub ID for that object, which is guaranteed to be globally unique and always match across servers.

To load an object from one server on another, given its ActivityPub ID, use the utils.loadRemoteObject method.

Limits

You can make no more than 3 requests per second. For authenticated requests, this is counted for each access token. For anonymous requests, this is per an IPv4 address or a /64 IPv6 subnet.

If you need to make many requests in a short succession, use the execute method to make up to 25 API calls in one network request.

Some methods may impose additional rate limits to prevent abuse.