# API Specification for twtxt.net

All *endpoints* will follow the [**HTTP** ***response status codes***](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status)

## Endpoints

`/api/login`

*METHOD* **POST**

*Body:*

{
    "username": "test",
    "password": "letmein",
    "device_name": "John's iPhone"
}

*Successful response:*

{
    "token": "ab98a396873f61d054b3365db7184fe0322c8765"
}

*Failure response:*

{
    "error_code": "login_fail",
    "error_message": "Invalid username and/or password."
}

`/api/logout`
---

*METHOD* **POST**

*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

`/api/register`
*METHOD* **POST**

*Body:*

{
    "username": "test",
    "password": "letmein",
    "email": "[e-mail]",
    "device_name": "John's iPhone"
}

*Successful response:*

{
    "token": "ab98a396873f61d054b3365db7184fe0322c8765"
}

`/api/follow`

*METHOD* **POST**

*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

*Body:*

{
    "nickname": "therealuser"
}

`/api/unfollow`

*METHOD* **POST**

*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

*Body:*

{
    "user_url": "https://twtxt.net/user/therealuser/twtxt.txt"
}

`/api/feeds`

*METHOD* **GET**

*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

*Response:*

[
    {
        "nickname": "therealuser",
        "user_url": "https://twtxt.net/user/therealuser/twtxt.txt"
    },
    {
        "nickname": "justauser",
        "user_url": "https://twtxt.net/user/justauser/twtxt.txt"
    }
]

`/api/feeds/create`

*METHOD* **PUT**

*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

*Response:*

{
    "feed_name": "News feed"
}

`/api/timeline`

*METHOD* **GET**
*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

*Parameters:*
`last_upadted_at=<timestamp>`

*Format:*
`<timestamp>` **->** *Last time the request was successfully made by client YYYY-MM-DDThh:mm:ssTZD*

*Response:*

[{
    "nickname": "therealuser",
    "user_url": "https://twtxt.net/user/therealuser/twtxt.txt",
    "text": "My first twtxt post",
    "timestamp": "2020-07-23T05:58:00Z"
 },
 {
    "nickname": "justauser",
    "user_url": "https://twtxt.net/user/justauser/twtxt.txt",
    "text": "My first twtxt post",
    "timestamp": "2020-07-23T07:15:00Z"
 }
]

`/api/discover`

*METHOD* **GET**

*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

*Response:*

[{
    "nickname": "therealuser",
    "user_url": "https://twtxt.net/user/therealuser/twtxt.txt",
    "text": "My first twtxt post",
    "timestamp": "2020-07-23T05:58:00Z"
 },
 {
    "nickname": "justauser",
    "user_url": "https://twtxt.net/user/justauser/twtxt.txt",
    "text": "My first twtxt post",
    "timestamp": "2020-07-23T07:15:00Z"
 }
]

`/api/post`

*METHOD* **POST**

*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

*Body:*

{
    "text": "My first twtxt post",
    "timestamp": "2020-07-23T05:58:00Z"
}

`/api/search/?q=`

*METHOD* **GET**

*Header:*
`Authorization: Token ab98a396873f61d054b3365db7184fe0322c8765`

*Parameters:*
`q=<search term>&last_update_at=2020-07-23T05:58:00Z`
*Supports `@mention` searchers:*
`q=@therealuser`
`last_update_at` **->** *timestamp for when the client last requested an update*