# Jellything API

Most endpoints require the `Accept` header to be present and set to
`application/json` and `image/avif` respectively. Any endpoint returning JSON, will report errors with an
object containing error string in the `error` key. Routes marked with `*`
require authentification.

The `jellyclient` crate already implements most API functionality. The
`jellycommon` crate provides useful structs for deserializing data (also
reexported in jellyclient).

```toml
# Cargo.toml
[depedencies]
jellyclient = { git = "https://codeberg.org/metamuffin/jellything.git" }
```

## General

### GET `/api/version`
Returns API version number.

### POST `/api/create_session`
Request body contains JSON with keys `username`, `password`, `expire` (in
seconds) and `drop_permissions` (a list of permissions, that this session cannot
use). The Response contains the session cookie as a string in JSON.

### GET* `/n/<id>`
Request a library node (either a directory or item). Returns it as `NodePublic`.

### GET* `/n/<id>/extended`
Request extended informationf for library node. Returns it as `ExtendedNode`.

## Assets

All asset endpoints redirect to the asset that you need. Returned images are
coded with AVIF. The `width` parameter is the width of the resolution you want to image to be.

> [!WARNING]
> The actual returned resolution must not be exactly what you requested.

### GET* `/n/<id>/asset?<role>&<width>`
Where `role` is one of `backdrop` or `poster` and 

### GET* `/n/<id>/thumbnail?<t>&<width>`
Returns a single frame from some track video of the media at a given time `t`. 

### GET* `/n/<id>/person/<index>/asset?<group>&<width>`
Returns headshot of a person from that node.

## Stream

### GET* `/stream/<id>?<format>&<index>&<profile>&<index>&<tracks>&<webm>`
Responds with the stream directly or a redirect to the actual source in case of
federation.