APIv1 Specification

The current APIv1 spec for twtxt.net and all Yarn.social pods is as follows.

NOTE: This is not a standardized protocol at all. It is however a standard HTTP/JSON API with JWT for authentication and authorization.

Transport

The transport is basic HTTP/1.1

You can connect to the API endpoints via any Web Browser client software such as Chrome, Firefox, cURL or any HTTP Web client libraires.

Serialization

Serialization is JSON. Every request requires a JSON payload even if it is empty. Most respones will send a JSON payload as their response but not all. (some may respond with an empty body and just a HTTP status).

Authentication

Authentication is done by submitting a set of credentials to the /api/v1/auth endpoint and receiving a JWT token. The JWT token is then used in a Token HTTP header in every subsequent request.

Endpoints

All endpoints have a /api/v1 URL prefix based on the twtxt.net pod you are talking to. For example to hit the /ping endpoint of twtxt.net:

$ curl -q -o - -H 'Accept: application/json' https://twtxt.net/api/v1/ping
{}

/ping

  • Purpose: To test the liveness of the API server
  • Method: GET
  • Request: none
  • Response:
    • 200 OK on success.

/whoami

  • Purpose: To test the liveness of the API server and return the Username of the currently logged in User.
  • Method: GET
  • Request: none
  • Response:
    • 200 OK on success with {"usernaem": "..."}

/register

  • Purpose: To create a new account
  • Method: POST
  • Request: {"username": ..., "password": ..., "email": ...}
  • Response:
    • 200 OK on success.
    • 400 Bad Request on parsing invalid, bad requests or validation failure.
    • 500 Internal Server Error if an internal error occurs.

/auth

  • Purpose: To authenticate an API client and create a JWT token.
  • Method: POST
  • Request: {"username": ..., "password": ...}
  • Response:
    • 200 OK with {"token": ...} on success with a valid JWT token.
    • 400 Bad Request on parsing invalid or bad requests.
    • 401 Unauthorized with “Invalid Credentials” on unsuccessful auth

/post

  • Purpose: To post a new twt
  • Method: POST
  • Request: {"text": ..., "post_as": ...}
  • Response:
    • 200 OK on success.
    • 400 Bad Request on parsing invalid or bad requests.
    • 401 Unauthorized with “Invalid Credentials” on unsuccessful auth
    • 500 Internal Server Error if an internal error occurs.

/sync

  • Purpose: To synchronize a local feed with a remote feed
  • Method: POST
  • Request: {"delete": ..., "feed": ..., "body": ...}
  • Response:
    • 200 OK on success with {"success": .., "error:" ..., "merged": ...}
    • 400 Bad Request on parsing invalid or bad requests.
    • 401 Unauthorized with “Invalid Credentials” on unsuccessful auth
    • 500 Internal Server Error if an internal error occurs.

/timeline

  • Purpose: To retrieve the contents of the currently authenticated user’s timeline.
  • Method: POST
  • Request: {"page": ...}
  • Response:
    • 200 OK with {"twts":[],"Pager":{"current_page":1,"max_pages":1,"total_twts":0}} on success.
    • 400 Bad Request on parsing invalid or bad requests.
    • 401 Unauthorized with “Invalid Credentials” on unsuccessful auth.
    • 500 Internal Server Error if an internal error occurs.

/discover

NOTE: No authentication is required for this endpoint.

  • Purpose: To retrieve the contents of the local pod’s timeline of all users.
  • Method: POST
  • Request: {"page": ...}
  • Response:
    • 200 OK with {"twts":[],"Pager":{"current_page":1,"max_pages":1,"total_twts":0}} on success.
    • 400 Bad Request on parsing invalid or bad requests.
    • 500 Internal Server Error if an internal error occurs.

/follow

  • Purpose: To follow a new user or feed.
  • Method: POST
  • Request: {"nick": ..., "url": ...}
  • Response:
    • 200 OK on success.
    • 400 Bad Request on parsing invalid or bad requests.
    • 401 Unauthorized with “Invalid Credentials” on unsuccessful auth.
    • 500 Internal Server Error if an internal error occurs.

/unfollow

  • Purpose: To unfollow a user or feed
  • Method: POST
  • Request: {"nick": ...}
  • Response:
    • 200 OK on success.
    • 400 Bad Request on parsing invalid or bad requests.
    • 401 Unauthorized with “Invalid Credentials” on unsuccessful auth
    • 500 Internal Server Error if an internal error occurs.

/upload

  • Purpose: To upload an image
  • Method: POST
  • Request:
    • multipart/form-data body that contains media_file field
  • Response:
    • 200 OK with {"Type":"mediaURI","Path":"<image URI>"} on success.
    • 400 Bad Request on parsing invalid or bad requests.
    • 401 Unauthorized with “Invalid Credentials” on unsuccessful auth.
    • 500 Internal Server Error if an internal error occurs.

/profile/:nick

  • Purpose: To get the profile of user/feed
  • Method: GET
  • Request: none
  • Response:
    • 200k OK with {"profile": ..., "links": ..., "alternatives": ... }. See types.ProfileResponse for more info
    • 404 Not found on user/feed not found
    • 500 Internal Server Error if an internal error occurs.

/profile/:nick/twts

  • Purpose: To get the twts of user/feed
  • Method: GET
  • Request: {"page": ...}
  • Response:
    • 200 OK with {"twts":[],"Pager":{"current_page":1,"max_pages":1,"total_twts":0}} on success.
    • 404 Not found on user/feed not found
    • 500 Internal Server Error if an internal error occurs.