JSON API Docs

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

$ curl 'https://twtxt.tilde.institute/api/json/version'
{
  "message": "getwtxt-ng dev"
}

Deleting Users

Delete a user by issuing a DELETE request to the /api/json/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/json/users?url=https://foo.ext/twtxt.txt'
{
  "message": "Deleted users successfully",
  "users_deleted": 1,
  "tweets_deleted": 34
}

Add a User

Add new user by submitting a POST request to the /api/json/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/json/users?url=https://foo.ext/twtxt.txt&nickname=foobar'
{
  "message": "You have been added and your passcode has been generated.",
  "passcode": "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.

Get all users:

$ curl 'https://twtxt.tilde.institute/api/json/users'
[
  {
    "id": 3,
    "nickname": "foo",
    "url": "https://example.com/twtxt.txt",
    "datetime_added": "2019-05-09T08:42:23.000Z",
    "last_sync": "2022-10-19T00:00:00.000Z"
  },
  {
    "id": 2,
    "nickname": "foobar",
    "url": "https://example2.com/twtxt.txt",
    "datetime_added": "2019-04-14T19:23:00.000Z",
    "last_sync": "2022-10-19T00:00:00.000Z"
  },
  {
    "id": 1,
    "nickname": "foo_barrington",
    "url": "https://example3com/twtxt.txt",
    "datetime_added": "2019-03-01T15:59:39.000Z",
    "last_sync": "2022-10-19T00:00:00.000Z"
  }
]

Query for user by URL:

$ curl 'https://twtxt.tilde.institute/api/json/users?url=https://example3.com/twtxt.txt'
[
  {
    "id": 1,
    "nickname": "foo_barrington",
    "url": "https://example3com/twtxt.txt",
    "datetime_added": "2019-03-01T15:59:39.000Z",
    "last_sync": "2022-10-19T00:00:00.000Z"
  }
]

Query for user by keyword:

$ curl 'https://twtxt.tilde.institute/api/json/users?q=bar'
[
  {
    "id": 2,
    "nickname": "foobar",
    "url": "https://example2.com/twtxt.txt",
    "datetime_added": "2019-04-14T19:23:00.000Z",
    "last_sync": "2022-10-19T00:00:00.000Z"
  },
  {
    "id": 1,
    "nickname": "foo_barrington",
    "url": "https://example3com/twtxt.txt",
    "datetime_added": "2019-03-01T15:59:39.000Z",
    "last_sync": "2022-10-19T00:00:00.000Z"
  }
]

Get all tweets:

$ curl 'https://twtxt.tilde.institute/api/json/tweets'
[
  {
    "id": "12",
    "user_id": "3",
    "nickname": "foo",
    "url": "https://example2.com/twtxt.txt",
    "datetime": "2019-05-13T12:46:20.000Z",
    "body": "It's been a busy day at work!",
    "mentions": [],
    "tags": [],
    "hidden": 0
  }
]

Query tweets by keyword:

$ curl 'https://twtxt.tilde.institute/api/json/tweets?q=getwtxt'
[
  {
    "id": "13",
    "user_id": "3",
    "nickname": "foo",
    "url": "https://example2.com/twtxt.txt",
    "datetime": "2019-05-13T13:46:20.000Z",
    "body": "I just installed getwtxt!",
    "mentions": [],
    "tags": [],
    "hidden": 0
  }
]

Get all tweets with tags:

$ curl 'https://twtxt.tilde.institute/api/json/tags'
[
  {
    "id": "14",
    "user_id": "3",
    "nickname": "foo",
    "url": "https://example2.com/twtxt.txt",
    "datetime": "2019-05-13T14:46:20.000Z",
    "body": "I love #programming!",
    "mentions": [],
    "tags": [
      "programming"
    ],
    "hidden": 0
  }
]

Query tweets by tag:

$ curl 'https://twtxt.tilde.institute/api/json/tags/programming'
[
  {
    "id": "14",
    "user_id": "3",
    "nickname": "foo",
    "url": "https://example2.com/twtxt.txt",
    "datetime": "2019-05-13T14:46:20.000Z",
    "body": "I love #programming!",
    "mentions": [],
    "tags": [
      "programming"
    ],
    "hidden": 0
  }
]

Get all tweets with mentions:

$ curl 'https://twtxt.tilde.institute/api/json/mentions'
[
  {
    "id": "15",
    "user_id": "3",
    "nickname": "foo",
    "url": "https://example2.com/twtxt.txt",
    "datetime": "2019-05-13T15:46:20.000Z",
    "body": "Hey @<foo_barrington https://example3.com/twtxt.txt> are you still working on that #project",
    "mentions": [
      {
        "nickname": "foo_barrington",
        "url": "https://example3.com/twtxt.txt"
      }
    ],
    "tags": [
      "project"
    ],
    "hidden": 0
  }
]

Query tweets by mention URL:

$ curl 'https://twtxt.tilde.institute/api/json/mentions?url=https://example3.com/twtxt.txt'
[
  {
    "id": "15",
    "user_id": "3",
    "nickname": "foo",
    "url": "https://example2.com/twtxt.txt",
    "datetime": "2019-05-13T15:46:20.000Z",
    "body": "Hey @<foo_barrington https://example3.com/twtxt.txt> are you still working on that #project",
    "mentions": [
      {
        "nickname": "foo_barrington",
        "url": "https://example3.com/twtxt.txt"
      }
    ],
    "tags": [
      "project"
    ],
    "hidden": 0
  }
]

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:

This is only supported via the Plain API.