diff --git a/docs/channels/index.md b/docs/channels/index.md new file mode 100644 index 0000000..19a41bc --- /dev/null +++ b/docs/channels/index.md @@ -0,0 +1,61 @@ +# Channels + +A channel is a persistent, signed collection of playlists with a publisher +identity. People follow a channel on their Art Computer, and the playlists you +add or reorder show up on their device. A playlist is a one-time selection. A +channel is something you keep. + +Reach for a channel when you want an ongoing, followable presence (a gallery, a +curator, a platform) rather than a single hand-off. + +!!! note "Build your playlists first" + A channel references playlists, not artworks. Make the playlists first with + [ff-cli](../ff-cli/index.md) or the [Hosted Feed](../hosted-feed/index.md), + then point a channel at them. + +## Make a channel + +=== "No-code (web)" + + [publisher.feralfile.com](https://publisher.feralfile.com) creates and + publishes channels with no API keys and no JSON. Sign in, assemble your + playlists into a channel, and publish. Publishing signs the channel under + your publisher identity so devices can verify it. + + This is the path for curators and partners. + +=== "API" + + Channels are first-class on the hosted feed. Reads are public. Writes need a + Bearer API key. + + Base URL: `https://feed.feralfile.com/api/v1` + + ```bash + # Create a channel (write — needs your API key) + curl -H "Authorization: Bearer your-api-key-here" \ + -H "Content-Type: application/json" \ + -X POST https://feed.feralfile.com/api/v1/channels \ + -d @channel.json + + # List channels (public) + curl https://feed.feralfile.com/api/v1/channels + ``` + + `channel.json` is a DP-1 channel: `title`, `slug`, a `publisher` identity, + and an ordered `playlists` array of playlist URLs, plus optional `summary`, + `coverImage`, and `curators`. The feed signs the channel on write. For the + full field list and every endpoint, see the canonical + [feed OpenAPI](https://github.com/display-protocol/dp1-feed-v2/blob/main/api/openapi.yaml) + and [channel extension schema](https://github.com/display-protocol/dp1/tree/main/extensions/channels). + +## Reach followers + +A channel carries at least one **feed** signature and one **publisher** +signature, and conforming players verify both before they trust it. Once a +device follows your channel, every playlist you add or reorder propagates to it. +That propagation is what a channel gives you over a one-off playlist. + +## Next step + +Build the playlists your channel will point at. See [ff-cli](../ff-cli/index.md). diff --git a/mkdocs.yml b/mkdocs.yml index fb9d4f2..a150376 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,7 @@ nav: - OTA: art-computer/how-it-works/ota.md - Specification: art-computer/specification.md - Hosted Feed: hosted-feed/index.md + - Channels: channels/index.md - Contact: https://feralfile.com/legal/contact # Pages built and served but intentionally absent from the nav.