getwtxt-ng - twtxt Registry

Plain API Docs

Retrieve the version of the instance by issuing a GET request to the /api/plain/version endpoint.

$ curl 'https://twtxt.tilde.institute/api/plain/version'
getwtxt-ng dev

Deleting Users

Delete a user by issuing a DELETE request to the /api/plain/users endpoint. This must include the X-Auth header with either the password returned after adding a user, or the admin password specified during configuration.

$ curl -X DELETE -H 'X-Auth: mypassword' 'https://twtxt.tilde.institute/api/plain/users?url=https://foo.ext/twtxt.txt'
200 OK

Add a User

Add new user by submitting a POST request to the /api/plain/users endpoint. If both ?url=X and ?nickname=X are not passed, or the user already exists in this registry, you will receive 400 Bad Request as a response. If you are unsure what went wrong, the error message should provide enough information for you to correct the request. On success, you will receive a 200.

To bulk add users, see the Administration section below.

$ curl -X POST 'https://twtxt.tilde.institute/api/plain/users?url=https://foo.ext/twtxt.txt&nickname=foobar'
You have been added! Your user's generated passcode is: d34db33f

Querying the Registry

Query responses are in descending chronological order. This means the newest user or tweet will be in the first row of the response, with older users or tweets in subsequent rows. Additionally, all queries accept ?page=N as a parameter, returning groups of 20 results. This may be omitted for the first page of results.

Columns are tab delimited:

Users:  Nickname, URL, Date, Last Sync
Tweets: Nickname, URL, Date, Body

Get all users:

$ curl 'https://twtxt.tilde.institute/api/plain/users'
foo               https://example.com/twtxt.txt     2019-05-09T08:42:23.000Z    2022-10-19T00:00:00.000Z
foobar            https://example2.com/twtxt.txt    2019-04-14T19:23:00.000Z    2022-10-19T00:00:00.000Z
foo_barrington    https://example3.com/twtxt.txt    2019-03-01T15:59:39.000Z    2022-10-19T00:00:00.000Z

Query for user by URL:

$ curl 'https://twtxt.tilde.institute/api/plain/users?url=https://example3.com/twtxt.txt'
foo_barrington    https://example3.com/twtxt.txt    2019-05-01T15:59:39.000Z    2022-10-19T00:00:00.000Z

Query for user by keyword:

$ curl 'https://twtxt.tilde.institute/api/plain/users?q=bar'
foobar            https://example2.com/twtxt.txt    2019-05-14T19:23:00.000Z    2022-10-19T00:00:00.000Z
foo_barrington    https://example3.com/twtxt.txt    2019-04-01T15:59:39.000Z    2022-10-19T00:00:00.000Z

Get all tweets:

$ curl 'https://twtxt.tilde.institute/api/plain/tweets'
foobar    https://example2.com/twtxt.txt    2019-05-13T12:46:20.000Z    It's been a busy day at work!
...

Query tweets by keyword:

$ curl 'https://twtxt.tilde.institute/api/plain/tweets?q=getwtxt'
foo_barrington    https://example3.com/twtxt.txt    2019-04-30T06:00:09.000Z    I just installed getwtxt

Get all tweets with tags:

$ curl 'https://twtxt.tilde.institute/api/plain/tags'
foo    https://example.com/twtxt.txt    2019-03-01T09:33:12.000Z    No, seriously, I need #help
foo    https://example.com/twtxt.txt    2019-03-01T09:32:05.000Z    Seriously, I love #programming!
foo    https://example.com/twtxt.txt    2019-03-01T09:31:02.000Z    I love #programming!

Query tweets by tag:

$ curl 'https://twtxt.tilde.institute/api/plain/tags/programming'
foo    https://example.com/twtxt.txt    2019-03-01T09:31:02.000Z    I love #programming!

Get all tweets with mentions:

$ curl 'https://twtxt.tilde.institute/api/plain/mentions'
foo               https://example.com/twtxt.txt     2019-02-28T11:06:44.000Z    @<foo_barrington https://example3.com/twtxt.txt> Hey!! Are you still working on that project?
bar               https://mxmmplm.com/twtxt.txt     2019-02-27T11:06:44.000Z    @<foobar https://example2.com/twtxt.txt> How's your day going, bud?
foo_barrington    https://example3.com/twtxt.txt    2019-02-26T11:06:44.000Z    @<foo https://example.com/twtxt.txt> Did you eat my lunch?

Query tweets by mention URL:

$ curl 'https://twtxt.tilde.institute/api/plain/mentions?url=https://foobarrington.co.uk/twtxt.txt'
foo    https://example.com/twtxt.txt    2019-02-26T11:06:44.000Z    @<foo_barrington https://example3.com/twtxt.txt> Hey!! Are you still working on that project?

Administration

Some additional functionality is provided to make administration easier, such as deletion of users and bulk adding users.

Delete a User:

See above API documentation.

Bulk Adding Users:

A POST request to the /api/plain/users/bulk endpoint must include the parameter source, containing the URL to a plain text file containing tab-separated rows. The fields must be: nickname, url, and optionally date added. The response will be in the same format, containing the users added plus the additional last sync time column.

The request must include the X-Auth header containing the administrator password.

$ curl -X POST -H 'X-Auth: admin_password' 'https://twtxt.tilde.institute/api/plain/users/bulk?source=https://my-old-instance/api/plain/users'
foo               https://example.com/twtxt.txt     2019-05-09T08:42:23.000Z    2022-10-19T00:00:00.000Z
foobar            https://example2.com/twtxt.txt    2019-04-14T19:23:00.000Z    2022-10-19T00:00:00.000Z
foo_barrington    https://example3.com/twtxt.txt    2019-03-01T15:59:39.000Z    2022-10-19T00:00:00.000Z