This document describes the HTTP, WebSocket, WebDAV, and discovery endpoints available while CrossPoint Reader is in File Transfer or Calibre Wireless mode.
- HTTP server: port 80
- WebSocket upload server: port 81
- UDP discovery listener: port 8134
- WebDAV: port 80, handled by the same HTTP server
Examples use crosspoint.local. If mDNS does not resolve on your network, use
the IP address shown on the device screen.
| Method | Path | Purpose |
|---|---|---|
GET |
/ |
Home/status page |
GET |
/files |
File manager page |
GET |
/settings |
Web settings page |
GET |
/fonts |
SD-card font manager page |
GET |
/plugins |
Plugins page (web settings of SD-card plugins) |
GET |
/js/jszip.min.js |
JavaScript asset used by the file manager |
GET |
/js/epub-optimizer.js |
File manager EPUB optimizer, loaded with JSZip only when needed |
GET |
/js/plugin-host.js |
Browser plugin host shared by the Plugins, File Manager, and /plugins-run pages |
HTML page responses, including 304 Not Modified, set the cookie cpPlugins=1 while
plugins are enabled and cpPlugins=0 otherwise. The page header uses it to hide the
Plugins link.
curl http://crosspoint.local/api/statusResponse:
{
"version": "1.0.0",
"firmwareFamily": "crosspoint",
"pluginApi": 1,
"pluginCapabilities": "catalog.lists,catalog.notices,catalog.bundle_install,catalog.version_tracking,catalog.compatibility,catalog.item_details,catalog.encoded_item_fields,catalog.list_index_mapping",
"ip": "192.168.1.100",
"mode": "STA",
"rssi": -45,
"freeHeap": 123456,
"uptime": 3600,
"device": "X4"
}| Field | Type | Description |
|---|---|---|
version |
string | Firmware version |
firmwareFamily |
string | Stable compatibility family; stock CrossPoint uses crosspoint |
pluginApi |
number | Numeric plugin API level used for catalog compatibility |
pluginCapabilities |
string | Comma-separated firmware capabilities used for catalog compatibility |
ip |
string | Device IP address |
mode |
string | "STA" for joined Wi-Fi or "AP" for hotspot mode |
rssi |
number | Wi-Fi RSSI in dBm; 0 in AP mode |
freeHeap |
number | Free heap in bytes |
uptime |
number | Seconds since boot |
deviceId |
string | With ?plugin=<name>: 64 hex chars, stable per device and plugin (SHA-256 of an on-device NVS secret and the name); omitted if NVS is unavailable |
device |
string | "X3" or "X4" hardware detection |
Lists files and folders under a directory.
curl "http://crosspoint.local/api/files?path=/Books"Query parameters:
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
No | / |
Directory to list |
Response:
[
{"name":"MyBook.epub","size":1234567,"isDirectory":false,"isEpub":true},
{"name":"Notes","size":0,"isDirectory":true,"isEpub":false}
]Hidden dotfiles are omitted unless the device setting showHiddenFiles is
enabled. System Volume Information and XTCache are always hidden/protected.
The saved-credential stores (/.crosspoint/wifi.json, opds.json,
koreader.json) can never be downloaded, uploaded, renamed, moved, deleted or
written by a plugin over the network, however the path is spelled.
Downloads a file from the SD card.
curl -OJ "http://crosspoint.local/download?path=/Books/MyBook.epub"Query parameters:
| Parameter | Required | Description |
|---|---|---|
path |
Yes | File path to download |
Protected dotfiles, System Volume Information, XTCache, and the credential
stores cannot be downloaded. EPUB files are served as application/epub+zip; other files use
application/octet-stream.
Uploads a file with HTTP multipart form data.
curl -X POST -F "file=@mybook.epub" "http://crosspoint.local/upload?path=/Books"Query parameters:
| Parameter | Required | Default | Description |
|---|---|---|---|
path |
No | / |
Destination directory |
overwrite |
No | off | 1 or true replaces a file with the same name |
Successful response:
File uploaded successfully: mybook.epub
Notes:
- Without
overwrite, an existing file with the same name is kept and the request fails with400"File already exists: ". - With
overwrite, the upload is written to<name>.partand replaces the existing file only when it is complete, so a failed upload keeps the old file. The card needs free space for both copies while the upload runs. A file already named<name>.partis replaced. If a folder has the name, the request fails with400"A folder with this name already exists: ". - EPUB cache data for the uploaded path is cleared after a successful upload.
- Uploading a book file (
.epub,.txt,.md,.xtc), here or through the WebSocket upload, marks the Library index stale, so the book appears the next time the Library opens. Hidden files and folders (names that start with.) don't mark it. - HTTP upload uses a 4 KB write buffer before flushing to the SD card.
Creates a folder.
curl -X POST -d "name=NewFolder&path=/" http://crosspoint.local/mkdirForm parameters:
| Parameter | Required | Default | Description |
|---|---|---|---|
name |
Yes | - | New folder name |
path |
No | / |
Parent folder |
Renames a file.
curl -X POST -d "path=/Books/old.epub&name=new.epub" http://crosspoint.local/renameForm parameters:
| Parameter | Required | Description |
|---|---|---|
path |
Yes | Existing file path |
name |
Yes | New file name, not a path |
Only files can be renamed through this endpoint. The old EPUB cache path is cleared before the rename.
Moves a file into an existing folder.
curl -X POST -d "path=/Books/mybook.epub&dest=/Read" http://crosspoint.local/moveForm parameters:
| Parameter | Required | Description |
|---|---|---|
path |
Yes | Existing file path |
dest |
Yes | Existing destination folder |
Only files can be moved through this endpoint. The old EPUB cache path is cleared before the move.
Deletes one or more files or empty folders.
curl -X POST -d "path=/Books/mybook.epub" http://crosspoint.local/delete
curl -X POST -d 'paths=["/Books/old.epub","/OldFolder"]' http://crosspoint.local/deleteForm parameters:
| Parameter | Required | Description |
|---|---|---|
path |
Yes, unless paths is provided |
Single path to delete |
paths |
Yes, unless path is provided |
JSON array of paths to delete |
System Volume Information, XTCache and the saved-credential stores cannot be
deleted. Hidden items (names that start with .) can be deleted. Non-empty
folders are rejected. EPUB cache data for deleted files is cleared.
Returns a streamed JSON array of editable settings. Each item contains common fields plus type-specific fields.
curl http://crosspoint.local/api/settings?keys= takes a comma-separated list of setting keys, without spaces, and
returns only those items in the same array format and in settings-list order.
Unknown keys are ignored. A plugin that needs one or two settings should use it
instead of reading the whole list.
curl 'http://crosspoint.local/api/settings?keys=koServerUrl,dictionaryName'Example item:
{
"key": "fontSize",
"name": "Reader Font Size",
"category": "Reader",
"type": "enum",
"value": 1,
"options": ["12 pt", "14 pt", "16 pt", "18 pt"]
}value is always an index into options, never the option's text. The
fontSize options depend on the selected family. A .cpfont family installed
at 10/12/14 pt offers those three sizes. TTF/OTF/TTC families offer the
standard 12/14/16/18 pt sizes. The fontFamily and dictionaryName options
also depend on the SD card contents.
Types:
| Type | Extra fields |
|---|---|
toggle |
value (0 or 1) |
enum |
value, options |
value |
value, min, max, step |
string |
value |
The font-family setting includes SD-card font families when they are installed.
Applies a partial settings update from a JSON object.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"fontSize":2,"showHiddenFiles":1}' \
http://crosspoint.local/api/settingsSuccessful response:
Applied 2 setting(s)
Lists installed SD-card font families. On devices that load TTF/OTF/TTC files,
these families appear with sizes: [0]. The 0 means that the font file has
no fixed point size; the reader offers 12, 14, 16, and 18 pt.
curl http://crosspoint.local/api/fontsResponse:
{
"maxFamilies": 128,
"vectorFonts": false,
"families": [
{
"name": "Literata",
"sizes": [12, 14, 16, 18],
"files": [
{"name": "Literata_12.cpfont", "size": 123456}
]
}
]
}Uploads one font file into a family folder: .cpfont, or .ttf/.otf on devices
with external RAM (vectorFonts: true in GET /api/fonts).
curl -X POST \
-F "family=Literata" \
-F "file=@Literata_12.cpfont" \
http://crosspoint.local/api/fonts/uploadThe handler validates the family name, filename extension, and magic bytes
(CPFONT, or a TrueType/OpenType header for .ttf/.otf) before accepting the
file.
Successful response:
{"ok":true}Deletes an installed font family.
This endpoint removes family subfolders. To remove a loose TTF/OTF/TTC file from a font root, delete the file from the SD card instead.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"family":"Literata"}' \
http://crosspoint.local/api/fonts/deleteSuccessful response:
{"ok":true}Lists saved OPDS servers. Passwords are never returned.
curl http://crosspoint.local/api/opdsResponse:
[
{
"index": 0,
"name": "My Catalog",
"url": "http://calibre.local:8080/opds",
"username": "reader",
"hasPassword": true
}
]Adds or updates an OPDS server. Include index to update an existing entry.
If password is omitted during an update, the existing password is preserved.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name":"My Catalog","url":"http://calibre.local:8080/opds","username":"reader","password":"secret"}' \
http://crosspoint.local/api/opdsDeletes an OPDS server by index.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"index":0}' \
http://crosspoint.local/api/opds/deleteLists saved Wi-Fi networks. Passwords are never returned.
curl http://crosspoint.local/api/wifiResponse:
[
{
"index": 0,
"ssid": "HomeWiFi",
"hasPassword": true,
"isLastConnected": true
}
]Adds or updates a saved Wi-Fi network. Include index to update an existing
entry. If password is omitted during an update, the existing password is
preserved.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"ssid":"HomeWiFi","password":"secret"}' \
http://crosspoint.local/api/wifiDeletes a saved Wi-Fi network by index.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"index":0}' \
http://crosspoint.local/api/wifi/deleteThe WebSocket path is used for fast binary uploads from the file manager and Calibre plugin workflows.
Connection:
ws://crosspoint.local:81/
Protocol:
- Client sends text:
START:<filename>:<size>:<path> - Server replies
READY - Client sends binary chunks
- Server sends
PROGRESS:<received>:<total>every 64 KB or at completion - Server sends
DONEwhen complete orERROR:<message>on failure
Example session:
Client -> START:mybook.epub:1234567:/Books
Server -> READY
Client -> [binary chunk]
Server -> PROGRESS:65536:1234567
...
Server -> DONE
Error messages include:
| Message | Cause |
|---|---|
ERROR:Upload already in progress |
A second upload was started before the first completed |
ERROR:Invalid START format |
Malformed START message or invalid size token |
ERROR:Failed to create file |
Destination file could not be opened |
ERROR:No upload in progress |
Binary data arrived without a matching START |
ERROR:Upload overflow |
Client sent more bytes than declared |
ERROR:Write failed - disk full? |
SD write failed |
ERROR:File already exists: <name> |
A file with that name exists; WebSocket uploads never replace files |
Incomplete WebSocket uploads are deleted on disconnect or error.
The server accepts two WebSocket connections at a time and closes further ones without a reply. It closes a connection that sends nothing for two minutes, which also deletes an unfinished upload.
The same HTTP server registers a WebDAV-compatible handler for file manager clients.
Supported methods:
OPTIONS, GET, HEAD, PUT, DELETE, PROPFIND, MKCOL, MOVE, COPY, LOCK, UNLOCK
Notes:
PUTwrites to a temporary.davtmpfile first, then renames it into place.- Protected paths are rejected.
LOCKandUNLOCKare accepted for client compatibility only. The server does not implement full WebDAV Class 2 locking semantics such as persistent locks or lock discovery.
The server listens on UDP port 8134. When it receives the text payload
hello, it replies to the sender with:
crosspoint (on <hostname>);81
The final field is the WebSocket upload port.
- Device joins an existing 2.4 GHz Wi-Fi network.
crosspoint.localis advertised with mDNS when available./api/statusreturns"mode": "STA"and RSSI in dBm.
- Device creates an open hotspot named
CrossPoint-Reader. - The device shows a Wi-Fi QR code and URL QR code.
- The fallback IP is typically
192.168.4.1. /api/statusreturns"mode": "AP"and"rssi": 0.- The hotspot's DNS answers every name with the device's IP. A
GETorHEADrequest whoseHostis any other domain name (not an IP address, a.localname or a single-label name such ascrosspoint) gets302 Location: http://<AP IP>/, so phones and computers can open the home page as a captive portal. Other methods are not redirected.
Calibre Wireless starts the same web server in STA mode and displays setup instructions plus WebSocket upload progress on the device screen.
Device capabilities for browser-side SD plugins (plugin.js). Plugins normally
reach these through the plugin host wrappers in /js/plugin-host.js
(api.relay, api.crypto, api.fetchToSd, api.writeFile); the raw
contracts are below. Outbound TLS is encrypted but the peer is not verified
(the transport ships no CA bundle).
Installed plugins that ship a plugin.js:
[{"name":"<folder>","dir":"<root>/<folder>","title":"<title>","mount":"settings"}, ...].
dir is where the plugin is installed (plugins keep their own files there);
title and mount come from the plugin's manifest.json when present.
Mount settings (the default) shows the card on the Plugins page (/plugins);
mount files shows it in the File Manager.
Serves one file from the plugin's folder (first root holding that name). Both
parameters must be single path components (no /, \, or ..); 404 when
the plugin, file, or a directory is requested; 500 when the file cannot be read.
Successful responses carry an ETag (MD5 of the file contents) and
Cache-Control: no-cache, so a browser keeps the file and checks it again on
each load. A request whose If-None-Match matches gets 304 with no body.
Makes an outbound HTTP(S) request for a plugin (any method; browsers can't, due
to CORS). Body: {"plugin":"<name>","method":"GET","url":"https://...","headers":{...},"body":"..."}.
- Success:
200with the upstream body verbatim. The upstream status is in theX-Relay-Statusresponse header, and its headers inX-Relay-Headersas JSON[["name","value"], ...]in receive order, duplicates kept (everySet-Cookie).api.relay()resolves to{status, headers, body}. - Redirects are not followed: a 3xx comes back with its
locationheader. - Limits: the upstream body is capped at 64KB. The device forwards the body
as it arrives and does not store it. Use
/api/fetchfor large files. A GET that fails with 502 can be retried with/api/fetch(api.relay()throws an error whosestatusis 502). - Errors:
400 {"error":"missing plugin/url"};502 {"error":"relay failed; ..."}when the request fails before any of the body arrives, or the upstreamContent-Lengthis over the cap (the device log names which). If the200has already started and the body is then cut short, or goes over the cap without aContent-Length, the device closes the connection.api.relay()reports that as the same 502 error.
Stateless wolfSSL primitives. Body {"op":"<op>", ...}; binary fields are
base64 in both directions, each at most 64KB encoded. Replies are 200 with
the result fields, or 200 {"error":"..."}.
op |
Request fields | Result |
|---|---|---|
random |
len (default 16, max 4096) |
data |
sha1 |
data |
data (20 bytes) |
sha256 |
data |
data (32 bytes) |
aesenc |
key, iv (16 bytes each), data |
data: AES-128-CBC with PKCS#7 padding |
aesdec |
key, iv, data (block-aligned) |
data: AES-128-CBC, padding left in place |
keygen |
none | public (SPKI DER), private (PKCS#8 DER): RSA key pair |
pubencrypt |
cert (X.509 DER), data |
data: RSAES-PKCS1-v1_5 to the certificate's key |
sign |
private (PKCS#8 DER), hash (20 bytes) |
data (128 bytes): raw RSA signature |
rsadec |
private (PKCS#8 DER), data (one modulus block) |
data: raw RSA private-key result, padding left in place |
pkcs12 |
data (the bundle), password |
key, cert (DER) |
Stores a protected book's content key for the reader. Body:
{"path":"/abs/book.epub","key":"<base64, 16 bytes>","expires":<epoch seconds, optional>}.
The device wraps the key with AES-256-GCM under a key derived from its NVS
secret and writes <path>.key; the header (including expires) is
authenticated, so the file only opens on this reader and its loan date cannot
be edited. The reader enforces expires when the book opens.
- Success:
200 {"ok":true}. - Errors:
400 {"error":"bad path/key"};500 {"error":"cannot store key"}.
Downloads a URL straight to SD, so a large body never passes through the
browser. Body: {"plugin":"<name>","url":"...","dest":"/abs/path","headers":{...},"offset":0,"maxBytes":0},
plus optional "method" (GET, POST, PUT, PATCH, or DELETE; default
GET) and "body" (a string, at most 4KB).
-
A request with a method other than GET, or with a non-empty body, is sent once: it is never replayed, and
offset/maxBytesmust be 0. A 3xx answer is not followed; it fails witherror:"http status". Use it for APIs that answer a POST with a large file. Such a request is not split into segments, so if the browser connection drops on a very large answer, check whetherdestwas installed. -
destmust be absolute with no..; missing parent folders are created. -
The transfer is staged in
<dest>.partand replacesdestonly when the whole body has arrived, so a failed update keeps the previous file. -
Installing a book file (
.epub,.txt,.md,.xtc) marks the Library index stale, so the book appears the next time the Library opens. Requests that end withcomplete:false, failed transfers, other file types, and hidden files or folders (names that start with.) don't mark it. -
A GET without a body follows up to 5 redirects.
headers(typically the plugin'sAuthorization) are sent only while the target keeps the starting URL's scheme, host, and port; a redirect elsewhere, including https→http, gets none. -
For a GET without a body, an answer cut short mid-transfer resumes on its own with a Range request.
-
Segments:
maxBytes(at most 4MB) ends the request after that many bytes withcomplete:false; send the next request withoffsetset to the returnedbytesto continue the same.part.api.fetchToSd()does this loop, keeping each browser request short. -
A long transfer answers early with
200chunked and sends whitespace every 5s to keep the browser connection open; the JSON result follows at the end. -
Result:
{"status":200,"bytes":N,"complete":true,"total":N}(totalwhen the server reported a size).statusis the upstream HTTP status, or -1 when no answer arrived.erroris set totransport failure,http status, orsd write failedwhen the file was not installed. A failed answer may includebody, up to its first 512 bytes (never ending in a cut UTF-8 character); currently only requests sent with a method other than GET or a non-empty body include it. -
Errors:
400 {"error":"bad url/dest"};400 {"error":"unsupported method"};400 {"error":"method must be a string"};400 {"error":"body must be a string"};400 {"error":"body over 4KB"};400 {"error":"offset and maxBytes need a GET without a body"};409 {"error":"offset mismatch","bytes":N}whenoffsetdoes not match the.partsize;502 {"error":"sd write failed" | "range unsupported" | "download truncated","bytes":N,"complete":false}.
Writes one small file to SD. The content is sent as a multipart file part
(api.writeFile() builds it), so binary data, including NUL bytes, arrives
intact. It streams to <path>.tmp and replaces path only after a complete,
non-empty body. path must be absolute, without .., and not a credential
store. A plugin keeps its own files in its install folder (api.dir). As with
/api/fetch, writing a book file marks the Library index stale.
- Success:
200 {"ok":true,"bytes":N}. - Errors:
400(bad path,empty body,missing file part,upload aborted);413 {"error":"too large"}over 256KB;500 {"error":"cannot write" | "sd write failed"}. The previous file is kept on every error.
External systems trigger SD-plugin actions without the web UI. The firmware
stores opaque {plugin, action, args} blobs (fixed 6-slot pool; args/result
< 192 bytes JSON); an open page hosting the plugin executes them. See
docs/sd-plugins.md for the full contract.
curl -X POST http://crosspoint.local/api/plugin-jobs \
-d '{"plugin":"<name>","action":"<action>","args":{"path":"/Books/somefile"}}'
# -> {"id":3} (503 {"error":"job queue full"} when all slots busy,
# or {"error":"out of memory"} if the queue cannot be allocated)Executor-side (used by the plugin host page): returns the next pending job
{"id":3,"claim":7,"action":"<action>","args":{...}} and marks it running, or {"id":0}.
A running job whose lease expires returns to pending and gets a new claim when re-claimed.
Executor-side: {"id":3,"claim":7,"ok":true,"result":{...}} -> {"ok":true}. The claim
must match the one from the claim response; a stale claim (the lease expired and another
executor re-claimed the job) gets 409 {"error":"stale claim"} and changes nothing.
curl "http://crosspoint.local/api/plugin-jobs/status?id=3"
# -> {"id":3,"state":"done","result":{"title":"...","dest":"/Books/Book.epub"}}States: pending, running, done, error, unknown (slot recycled —
poll promptly after completion).
Headless executor page: loads every plugin with its UI hidden so registered actions run. Keep it open (browser tab or embedded webview) while jobs are queued; jobs enqueued with no page open stay pending until one opens.