aboutsummaryrefslogtreecommitdiff
path: root/castle-search/README.md
diff options
context:
space:
mode:
authorIgor Soarez <igor@soarez.org>2026-11-18 12:11:11 +0000
committerIgor Soarez <igor@soarez.org>2026-11-18 12:11:11 +0000
commitf8835d53b96bb6e4152bc5bf84e61b8b54396008 (patch)
treed3815441efcb5a87498dfff8054c0786c84afffd /castle-search/README.md
parent910ac7cd424f6401ea042a84603c42ba055994f8 (diff)
castle-search: X.com: read posts whole with thread and replies, profiles, trends
/x-post, /x-user and /x-trends beside /x-search, sharing its limits and its sign-in. Posts now carry photos (image link, alt text), videos, link cards and the quoted post's time. A post's own page lists the quoted post's time first; the probe now takes the post's own linked time.
Diffstat (limited to 'castle-search/README.md')
-rw-r--r--castle-search/README.md36
1 files changed, 23 insertions, 13 deletions
diff --git a/castle-search/README.md b/castle-search/README.md
index 1b74884..e8b204a 100644
--- a/castle-search/README.md
+++ b/castle-search/README.md
@@ -47,23 +47,33 @@ switch engines, because this protocol has no field for one. There is no
authentication: bind it to loopback (the default) or a trusted address.
`GET /health` answers `{"status": true}`.
-### X search
+### X.com: search, posts, profiles, trends
-`POST /x-search` searches X (Twitter) instead: `{"query": "from:nasa", "count":
-10, "sort": "latest"}` in, `{"query", "sort", "posts": [...]}` out, each post
-with its link, author, time, text, counts and any quoted post. The query is X's
-own search syntax. It needs the browser signed in to X — X serves search to
-nobody else — and it says so when it is not, rather than returning nothing.
-`GET /openapi.json` describes it, so Open WebUI can offer it as a tool. Free per
-search, where xAI's own X search charges per post returned.
+Four reads of X (Twitter), each `POST` a JSON object and get JSON back:
+
+| Route | In | Out |
+|---|---|---|
+| `/x-search` | `query` (X's own search syntax), `count`, `sort` (`latest` or `top`) | the posts |
+| `/x-post` | `url` (a post link or its id), `replies` | the post whole, the `thread` above it when it is a reply, its top `replies` |
+| `/x-user` | `handle`, `count` | the `profile` (bio, location, website, joined, exact follower, following and post counts) and its latest posts |
+| `/x-trends` | `tab`: `trending`, `news`, `sports`, `entertainment`, `for_you` | the trends, each with a `query` for `/x-search` |
+
+Each post comes with its link, author, time, text, counts, photos (X's image
+link and alt text), videos (a still), a link card and any quoted post. A search
+result X cut short is marked `truncated`; `/x-post` reads it whole. It needs the
+browser signed in to X, since X serves none of this to anybody else, and it
+says so when it is not, rather than returning nothing. `GET /openapi.json`
+describes all four, as "X.com", so Open WebUI can offer them as tools. Free,
+where xAI's own X search charges per post returned. Trends are for the
+signed-in account's region.
X keeps only the posts near the screen in the page, so it scrolls and collects
-by link, up to 20 posts. A search takes 4–7 s.
+by link, up to 20 posts (or replies). A read takes 4–7 s.
-It is limited so the account reads X like a person, not a scraper
-(`src/x-limits.ts`): one search at a time, at least 10 s between them (a search
-that comes sooner waits), and at most 30 an hour and 150 a day, beyond which a
-search fails saying when the next may run. The counts live in memory, so a
+All four share one set of limits, so the account reads X like a person, not a
+scraper (`src/x-limits.ts`): one read at a time, at least 10 s between them (a
+read that comes sooner waits), and at most 30 an hour and 150 a day, beyond which a
+read fails saying when the next may run. The counts live in memory, so a
restart starts them afresh.
Signed out, it signs back in by itself when `CCS_X_LOGIN_FILE` names a JSON