> ## Documentation Index
> Fetch the complete documentation index at: https://help.xitter.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Endpoints

> Every endpoint in the public API, and the objects it returns.

Paths are relative to `https://<instance>/api/v1`. **Read** endpoints work with any token; **write** endpoints need a write token.

## Accounts

| Method | Path | Scope | Description |
| - | - | - | - |
| `GET` | `/me` | read | Your account. |
| `GET` | `/users/{screen_name}` | read | An account. |
| `GET` | `/users/{screen_name}/posts` | read | Its posts and reposts, newest first. `replies=true` includes replies. |
| `GET` | `/users/{screen_name}/followers` | read | Who follows it (up to `limit`, 200 at most). |
| `GET` | `/users/{screen_name}/following` | read | Who it follows. |
| `POST` | `/users/{screen_name}/follow` | write | Follow (asks, for a protected account). `DELETE` to unfollow. |

## Posts and timelines

| Method | Path | Scope | Description |
| - | - | - | - |
| `GET` | `/timeline` | read | Posts and reposts from you and the accounts you follow, newest first. |
| `GET` | `/posts/{id}` | read | One post. |
| `GET` | `/posts/{id}/replies` | read | Its replies. |
| `POST` | `/posts` | write | Post. See below. |
| `DELETE` | `/posts/{id}` | write | Delete one of your posts. |
| `POST` | `/posts/{id}/like` | write | Like. `DELETE` to undo. |
| `POST` | `/posts/{id}/repost` | write | Repost. `DELETE` to undo. |
| `POST` | `/posts/{id}/bookmark` | write | Bookmark. `DELETE` to undo. |

### Creating a post

`POST /posts` takes:

| Field | Required | Description |
| - | - | - |
| `text` | yes | The post's text. |
| `reply_to` | no | A post id to reply to. |
| `quote` | no | A post id to quote. |
| `media_ids` | no | Up to 4 ids from the [media endpoints](/api/media). |
| `sensitive` | no | Marks the media sensitive. |

## Search

| Method | Path | Scope | Description |
| - | - | - | - |
| `GET` | `/search/posts?q=` | read | Posts matching a search, with the same operators as the app (`from:`, `filter:media`, ...). `sort=top` for top posts. |
| `GET` | `/search/users?q=` | read | Accounts matching a name or handle. |

## Media

See [Media uploads](/api/media).

## Objects

### Post

| Field | Description |
| - | - |
| `id` | Post id. |
| `text` | Text. |
| `created_at`, `edited_at` | Times. |
| `url` | Link to the post. |
| `author` | An account. |
| `reply_to`, `quote_of` | Related posts. |
| `sensitive` | Whether its media is marked sensitive. |
| `counts` | `likes`, `reposts`, `replies`, `quotes`, `bookmarks`, `views`. |
| `viewer` | Whether you liked, reposted or bookmarked it. |
| `media` | Attached media. |
| `reposted_by`, `reposted_at` | In timelines, set when the entry is a repost. |

### Account

| Field | Description |
| - | - |
| `id`, `screen_name`, `name` | Identity. |
| `bio`, `location`, `website` | Profile text. |
| `avatar_url`, `banner_url` | Images. |
| `verified_type` | Badge type. |
| `protected` | Whether it's a protected account. |
| `created_at`, `url` | When it was made, and a link to it. |
| `counts` | `posts`, `followers`, `following`, `likes`. |
| `viewer` | `following`, `followed_by`. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.