Registry

Since twtxt is decentralized by design, features like the timeline are limited to the twtxt users followed by you. To provide a global search for mentions or hash tags, the client will be able to query so called registries.

A reference implementation is available at twtxt-registry (source) in nodejs and a demo instance is running at twtxt-registry (demo).

The client will support multiple registries at the same time, to circumvent possible single point of failures. The registries should sync each others user list by using the users endpoint.

Format specification

Writing to the registry

The responses return proper status code (200 OK) and the description of the status code or a detailed error message.

Reading from the registry

The responses contain one status per line, each of which is equipped with reference to the poster followed by a TAB and an ISO 8601 date/time string followed by a TAB character (\t) to separate it from the actual text.

General rules

  1. All lists are sorted by timestamp in descending order (most recent one first)
  2. All lists support the page query parameter to get the next page of the result set.
  3. The response must be encoded with UTF-8 and must use LF (\n) as line separators.

API Endpoints

The url to the registry consists of its basepath (e.g. https://registry.twtxt.org/api/). The format (e.g. plain) is appended, because we might support json or xml format sooner or later.

The following parameters:

  • basePath: https://registry.twtxt.org/api/
  • format: plain
  • endpoint: tags/twtxt

will call this url: https://registry.twtxt.org/api/plain/tags/twtxt.

Add new User

Add a new Twtxt User to the Registry (Status Code is 200):

$ curl -X POST https://registry.twtxt.org/api/plain/users?url=https://example.org/twtxt.txt&nickname=example
OK

If it fails to add a new Twtxt User to the Registry (Status Code is 400):

$ curl -X POST https://registry.twtxt.org/api/plain/users?url=https://example.org/twtxt.txt
Bad Request: `nickname` is missing

See latest tweets in the Registry (e.g. <https://registry.twtxt.org/api/plain/tweets>):

$ curl https://registry.twtxt.org/api/plain/tweets
@<example https://example.org/twtxt.txt>        2016-02-06T21:32:02.000Z        @erlehmann is messing with timestamps in @buckket #twtxt :)
@<example https://example.org/twtxt.txt>        2016-02-06T12:14:18.000Z        Simple nodejs script to convert your twitter timeline to twtxt: https://t.co/txnWsC5jvA ( find my #twtxt at https://t.co/uN1KDXwJ8B )

Search for tweets

To query for tweets, which contain a specific word, use the tweets endpoint and the q query parameter.

$ curl https://registry.twtxt.org/api/plain/tweets?q=twtxt
@<buckket https://buckket.org/twtxt.txt>        2016-02-09T12:42:26.000Z        Do we need an IRC channel for twtxt?
@<buckket https://buckket.org/twtxt.txt>        2016-02-09T12:42:12.000Z        Good Morning, twtxt-world!

Query for mentions

To query for all tweets, which mention a specific user, use the mentions endpoint and the url query parameter.

$ curl https://registry.twtxt.org/api/plain/mentions?url=https://buckket.org/twtxt.txt
@<example https://example.org/twtxt.txt>        2016-02-09T12:57:59.000Z        @<buckket https://buckket.org/twtxt.txt> something like https://gitter.im/ or a freenode channel?
@<example https://example.org/twtxt.txt>        2016-02-08T22:51:47.000Z        @<buckket https://buckket.org/twtxt.txt> looks nice ;)

Query for tags

To query for all tweets, which contain a specific tag like #twtxt, use the tags endpoint and prepend the tag.

$ curl https://registry.twtxt.org/api/plain/tags/twtxt
@<example https://example.org/twtxt.txt>        2016-02-06T21:32:02.000Z        @erlehmann is messing with timestamps in @buckket #twtxt :)
@<example https://example.org/twtxt.txt>        2016-02-06T12:14:18.000Z        Simple nodejs script to convert your twitter timeline to twtxt: https://t.co/txnWsC5jvA ( find my #twtxt at https://t.co/uN1KDXwJ8B )

Query for users

To query for a user list, use the users endpoint and refine with the q query parameter.

$ curl https://registry.twtxt.org/api/plain/users?q=example
<@example https://example.org/twtxt.txt>        2016-02-09T12:42:26.000Z        example
<@example https://example.org/42.twtxt.txt>     2016-02-10T13:20:10.000Z        example42