dial

Build on dial

The dial website is one client of a public API, and yours can be another. A phone app, a reader for the terminal, a bot that posts your sourdough timer: they all get the same ranked feeds, with the same dials and the same caught-up point.

Reading needs no key. Posting, following and anything on someone’s behalf goes through OAuth 2 with PKCE, so you never handle a password or a passkey.

Reading without a token

Any read endpoint works anonymously. Send an X-Dial-Device header with a random string you keep per install (16 to 64 URL-safe characters). That’s what gives each reader their own list of seen posts, so the caught-up point works.

curl -H 'X-Dial-Device: 9f2c6b1d0e7a4c3b8a5d' \
  'https://dial.steele.app/api/v1/feed?dials=f6l2w8p8v3n0a1'

Dials

Feeds take a dials string. Each letter is followed by a number: f friends to discovery (0-10), l calm to lively (0-10), w, p and v for how much you want words, photos and clips (0 leaves that format out), n news (0 or 1), a AI-made media (0 off, 1 turned down, 2 normal) and u caught-up point (0 or 1). Leave a letter out and it falls back to the user’s saved dials, then the defaults. Every ranked post comes with a why string. Please show it.

Signing people in

  1. Sign in on dial, open Settings and register your app with its redirect URIs. You get a client ID. There’s no client secret: every app is a public client.
  2. Send the person to /oauth/authorize with response_type=code, client_id, redirect_uri, scope (read, or read write), state, and a code_challenge made with S256. Plain challenges are refused.
  3. They approve, and dial redirects back with code and your state.
  4. POST to /oauth/token with grant_type=authorization_code, code, redirect_uri, client_id and code_verifier. You get an access token, valid for 30 days, and a refresh token.
  5. Send Authorization: Bearer <token>. When it expires, POST grant_type=refresh_token. Refresh tokens are single use; store the new one each time.

Redirect URIs can be https, http://localhost or 127.0.0.1 on any port, or an app scheme with a dot in it such as com.example.reader:/callback. They have to match exactly. /oauth/revoke takes a token and ends that session.

Tell us what people saw

Ranking runs on what people save, finish and come back to, counted per view. If your app shows posts and never reports views, those posts look unseen and the ranking for everyone gets worse. POST batches to /events: view once at least half a post has been on screen for a second, open when someone opens it, finish when a clip plays to 90%, an article is read to the end or every photo in a set has been seen.

Limits

300 requests a minute per token, 600 a minute per IP address without one. Past that you get 429 with a Retry-After header. Posting has its own limits (30 posts an hour for most accounts, 10 in an account’s first three days). Errors are JSON with an error code and a message written for people, so you can show the message as it is.

House rules for apps

Show the why line and the “Made with AI” label. Don’t hide the caught-up point behind autoplay. Don’t scrape what you could ask for, and don’t post for anyone without them pressing a button that says so. Apps that break the rules lose their client ID.

Reference

Base URL https://dial.steele.app/api/v1. The machine-readable spec is at /api/v1/openapi.json (OpenAPI 3.1).

Feeds

EndpointWhat it doesToken
GET /feedRanked feed for the viewer’s dials
dials cursor limit wide seen
optional
GET /feed/followingPosts and reposts from accounts the user follows, newest first
before
read
GET /feedsPublished feeds, most followed first
sort
optional
POST /feedsPublish dial settings as a feedwrite
GET /feeds/{slug}One published feednone
PATCH /feeds/{slug}Edit your feedwrite
DELETE /feeds/{slug}Delete your feedwrite
GET /feeds/{slug}/postsA published feed, ranked for this viewer
cursor limit wide seen
none
POST /feeds/{slug}/followFollow a feedwrite
DELETE /feeds/{slug}/followUnfollow a feedwrite
GET /communities/{slug}/postsA community: ranked, or newest first with sort=latest
sort dials cursor limit wide seen before
none
GET /tags/{tag}Posts with a tag, newest first
before
none
GET /exploreTrending tags, communities, accounts getting found, feeds to try, best of the last daynone
GET /searchSearch people, tags and posts
q
none

Posts

EndpointWhat it doesToken
POST /postsCreate a post, reply or quotewrite
GET /posts/{id}One post with up to 6 ancestorsnone
DELETE /posts/{id}Delete your postwrite
GET /posts/{id}/repliesDirect replies, oldest first
after
none
POST /posts/{id}/saveSave (private bookmark; the strongest ranking signal)write
DELETE /posts/{id}/saveUnsavewrite
POST /posts/{id}/repostRepostwrite
DELETE /posts/{id}/repostUndo repostwrite
POST /posts/{id}/reportReport a postnone
POST /eventsReport what the viewer saw. This is what ranking runs on, so please send it.none

People

EndpointWhat it doesToken
GET /users/{handle}Profilenone
GET /users/{handle}/postsSomeone’s posts, newest first
filter before
none
GET /users/{handle}/followersFollowers
before
none
GET /users/{handle}/followingFollowing
before
none
POST /users/{handle}/followFollowwrite
DELETE /users/{handle}/followUnfollowwrite
POST /users/{handle}/blockBlockwrite
DELETE /users/{handle}/blockUnblockwrite
POST /users/{handle}/muteMutewrite
DELETE /users/{handle}/muteUnmutewrite

Account

EndpointWhat it doesToken
GET /meThe signed-in user, saved dials and unread alert countread
PATCH /meUpdate name, bio, default reply rule or saved dialswrite
GET /me/savedSaved posts, newest save first
before
read
GET /me/feedsFeeds the user follows (their own included)read
GET /me/muted-wordsMuted wordsread
POST /me/muted-wordsMute a wordwrite
DELETE /me/muted-wordsUnmute a word
word
write
GET /notificationsAlerts: replies, mentions, quotes, reposts, follows
before
read
POST /notifications/readMark all alerts readwrite