Skip to content



NeoDB has a set of API endpoints mapping to its functions like marking a book or listing collections, they can be found in swagger based API documentation at /developer/ of your running instance, a version of it is available on our flagship instance.

NeoDB also supports a subset of Mastodon API, details can be found in Mastodon API documentation.

Both set of APIs can be accessed by the same access token.

How to authorize

Create an application

you must have at least one URL included in the Redirect URIs field, e.g., or use urn:ietf:wg:oauth:2.0:oob if you don't have a callback URL.

curl \
  -d client_name=MyApp \
  -d redirect_uris= \
  -d website=

and save of the client_id and client_secret returned in the response:

  "client_id": "CLIENT_ID",
  "client_secret": "CLIENT_SECRET",
  "name": "MyApp",
  "redirect_uri": "",
  "vapid_key": "PUSH_KEY",
  "website": ""

Guide your user to open this URL

Once authorizated by user, it will redirect to with a code parameter:

Obtain access token with the following POST request:

curl \
    -d "client_id=CLIENT_ID" \
    -d "client_secret=CLIENT_SECRET" \
    -d "code=AUTH_CODE" \
    -d "redirect_uri=" \
    -d "grant_type=authorization_code"

and access token will be returned in the response:

    "access_token": "ACCESS_TOKEN",
    "token_type": "Bearer",
    "scope": "read write"

Use the access token to access protected endpoints like /api/me

curl -H "Authorization: Bearer ACCESS_TOKEN" -X GET

and response will be returned accordingly:

{"url": "", "external_acct": "[email protected]", "display_name": "XYZ", "avatar": "https://yyy.zzz/xxx.gif"}