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 auth500 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 auth500 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 auth500 Internal Server Error
if an internal error occurs.
/upload
- Purpose: To upload an image
- Method:
POST
- Request:
multipart/form-data
body that containsmedia_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": ... }
. Seetypes.ProfileResponse
for more info404 Not found
on user/feed not found500 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 found500 Internal Server Error
if an internal error occurs.