iPX
API ipx 1.0.0
The HTTP API of an iPX server: everything the page does, a script can do. Every request
and answer is JSON unless an item says otherwise. The page is served by ipx-web, which passes
/api and /media on to ipx at the same address, so a script talks to
the address people open in a browser.
Signing in
Send an API token, made in Settings under API tokens or with POST /api/tokens:
Authorization: Bearer ipx_…A token acts as the person who made it, and is an admin only if they are. A browser signs in
with POST /api/login instead and is
given a cookie. Behind Cloudflare Access, Access stops a request with no Access sign-in before
iPX sees it: send an Access service token's CF-Access-Client-Id and
CF-Access-Client-Secret beside the API token.
Errors
A request that fails answers with its status and a sentence saying why, as plain text:
401 not signed in, 403 an admin's to do, 404 not there or
not yours, 400 a request that cannot be done as asked, 409 a conflict
the answer explains.
Ids
A feed's id is a short name made from its title, such as 99-invisible, and
appears in the page's address when the feed is open. An episode is its feed's id and its
guid, the guid URL-encoded in a path. A file (an enclosure) has a number. Times are
Unix seconds.
Modules
- auth
- Who you are, signing in and out, and API tokens.
- feeds
- Your subscriptions: list, subscribe, change, unsubscribe, check, OPML.
- entries
- Episodes and posts: list, search, mark read or kept, save where you are.
- files
- Downloading, deleting and playing an episode’s file.
- directory
- Browse the directory and subscribe from it; iPX asks it on your behalf.
- server
- Its counts and version, and live updates.
- admin
- Server settings, accounts, the log and the directory’s administration. Admins only.
Types
- Credentials
- A name and password.
- Me
- Who is signed in.
- MePatch
- What
PATCH /api/mechanges. - Token
- An API token, as listed.
- NewToken
- A token to make.
- NewTokenMade
- A token just made: the only time it is shown.
- FeedRow
- A feed as you see it: the feed, your settings for it and its counts for you.
- FailingRow
- Why a feed has been failing.
- NewFeed
- A feed to subscribe to.
- Added
- A feed subscribed to.
- FeedPatch
- What
PATCH /api/feeds/{id}changes. Leave out what stays;nullclears a field that can be cleared. - Marked
- HowMany
- Queued
- FetchBody
- What to check.
- OpmlBody
- Imported
- Page
- Which episodes, as query parameters.
- EntryPage
- A page of episodes.
- EntryRow
- An episode or post, with your state for it.
- EncRow
- An episode’s file.
- Flags
- Position
- Force
- A query parameter.
- PopularRow
- A feed in the directory. Never its address: subscribe by its id.
- Listed
- A feed’s page in the directory.
- ListedItem
- Subscribed
- Status
- Event
- One live update.
evsays which, and the rest depends on it. - Settings
- The server’s settings.
- SettingsPatch
- What
PATCH /api/settingschanges. Leave out what stays. - UserRow
- An account.
- NewUser
- UserPatch
- LogQuery
- Query parameters.
- LogPage
- LogLine
- DirectoryStatus
- DirectoryAdmin
- BlockedRow
- A feed the directory keeps out. Never its address.
- Instance
- A server sharing with the directory.
- SnapshotResult
- What the directory made of a share.