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
- 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.
- Send the person to
/oauth/authorizewithresponse_type=code,client_id,redirect_uri,scope(read, orread write),state, and acode_challengemade withS256. Plain challenges are refused. - They approve, and dial redirects back with
codeand yourstate. - POST to
/oauth/tokenwithgrant_type=authorization_code,code,redirect_uri,client_idandcode_verifier. You get an access token, valid for 30 days, and a refresh token. - Send
Authorization: Bearer <token>. When it expires, POSTgrant_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
| Endpoint | What it does | Token |
|---|---|---|
GET /feed | Ranked feed for the viewer’s dialsdials cursor limit wide seen | optional |
GET /feed/following | Posts and reposts from accounts the user follows, newest firstbefore | read |
GET /feeds | Published feeds, most followed firstsort | optional |
POST /feeds | Publish dial settings as a feed | write |
GET /feeds/{slug} | One published feed | none |
PATCH /feeds/{slug} | Edit your feed | write |
DELETE /feeds/{slug} | Delete your feed | write |
GET /feeds/{slug}/posts | A published feed, ranked for this viewercursor limit wide seen | none |
POST /feeds/{slug}/follow | Follow a feed | write |
DELETE /feeds/{slug}/follow | Unfollow a feed | write |
GET /communities/{slug}/posts | A community: ranked, or newest first with sort=latestsort dials cursor limit wide seen before | none |
GET /tags/{tag} | Posts with a tag, newest firstbefore | none |
GET /explore | Trending tags, communities, accounts getting found, feeds to try, best of the last day | none |
GET /search | Search people, tags and postsq | none |
Posts
| Endpoint | What it does | Token |
|---|---|---|
POST /posts | Create a post, reply or quote | write |
GET /posts/{id} | One post with up to 6 ancestors | none |
DELETE /posts/{id} | Delete your post | write |
GET /posts/{id}/replies | Direct replies, oldest firstafter | none |
POST /posts/{id}/save | Save (private bookmark; the strongest ranking signal) | write |
DELETE /posts/{id}/save | Unsave | write |
POST /posts/{id}/repost | Repost | write |
DELETE /posts/{id}/repost | Undo repost | write |
POST /posts/{id}/report | Report a post | none |
POST /events | Report what the viewer saw. This is what ranking runs on, so please send it. | none |
People
| Endpoint | What it does | Token |
|---|---|---|
GET /users/{handle} | Profile | none |
GET /users/{handle}/posts | Someone’s posts, newest firstfilter before | none |
GET /users/{handle}/followers | Followersbefore | none |
GET /users/{handle}/following | Followingbefore | none |
POST /users/{handle}/follow | Follow | write |
DELETE /users/{handle}/follow | Unfollow | write |
POST /users/{handle}/block | Block | write |
DELETE /users/{handle}/block | Unblock | write |
POST /users/{handle}/mute | Mute | write |
DELETE /users/{handle}/mute | Unmute | write |
Account
| Endpoint | What it does | Token |
|---|---|---|
GET /me | The signed-in user, saved dials and unread alert count | read |
PATCH /me | Update name, bio, default reply rule or saved dials | write |
GET /me/saved | Saved posts, newest save firstbefore | read |
GET /me/feeds | Feeds the user follows (their own included) | read |
GET /me/muted-words | Muted words | read |
POST /me/muted-words | Mute a word | write |
DELETE /me/muted-words | Unmute a wordword | write |
GET /notifications | Alerts: replies, mentions, quotes, reposts, followsbefore | read |
POST /notifications/read | Mark all alerts read | write |