kg/x

HTTP API за X: публикация, профил, отговори, търсене и изтегляне на видео, звук или снимка. Панелът на същия адрес е тестова площадка за всички ендпойнти.

Базов адрес: /api/v1. Машинно описание: /api/v1/openapi.json.

Публикациите и профилите се четат и без акаунт. Търсенето, последователите, харесванията и /account искат влязъл облачен браузър или качен cookies.txt. Cookies се пращат само през директния IP на сървъра.

Автентикация и права

Ключът се създава от панела и се показва веднъж. На диска е само HMAC. Подава се в хедър:

HTTP

Authorization: Bearer xpk_…
X-API-Key: xpk_…

Ключ в URL (?api_key=, ?token= и подобни) се отказва и ключът се изключва. След 20 грешни ключа от едно IP за 10 минути адресът се заключва за 15 минути.

data — resolve, suggest, search, explore, профил и разделите му, публикация, акаунт
download — info, jobs, файлове
status — маршрути, агент, опашка
admin — настройки, тест на маршрути, cookies, агент

Всеки ключ има лимит заявки в минута, задачи на час, едновременни задачи, срок и по избор списък позволени IP адреси. Отговорите носят X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset и X-Request-Id.

Площадката в панела вика същото API със сесията и хедър X-Playground: 1. От чужд сайт този хедър не минава: няма CORS.

Грешки

Тяло: {"error":{"code","message","details"?},"request_id"}. code е стабилен на английски. message е на български.

401 missing_api_key, invalid_api_key, key_expired, login_required
403 key_disabled, ip_not_allowed, insufficient_scope
404 not_found, job_not_found, file_gone
422 no_media, too_long, validation_error
429 rate_limited, jobs_quota_exceeded, too_many_jobs, auth_locked
400 key_in_url, invalid_url
502 x_blocked, x_error, route_unreachable

Данни

GET /resolve?url=

Линк, @handle или id на публикация. Връща type (tweet или user), id, screen_name, url.

GET /tweet?id=

Публикация: text, created_at, lang, metrics (likes, reposts, replies, quotes, bookmarks, views), user, media[] с варианти (mp4 / hls), url.

GET /user?screen_name=

Профил: име, описание, локация, аватар, последователи, following, брой публикации, verified, protected.

Страници

count е 1–40 (по подразбиране 20). cursor е continuation от предишния отговор. Празен низ не се подава.

GET /user/tweets и останалите раздели

Всички връщат user, items (публикации), users (хора, при последователи) и continuation. sort=likes е за публикации, публикации с отговори и отбелязани.

Път	Какво е
`/user/tweets`	Публикации
`/user/with_replies`	Публикации и отговори
`/user/replies`	Само отговори
`/user/media` `/photos` `/videos` `/live`	Медия
`/user/likes`	Харесвания. Заключени харесвания връщат празен списък.
`/user/highlights` `/articles` `/reposts` `/originals`	Отбелязани, статии, репостове, оригинални
`/user/super-follows`	Публикации за абонати
`/user/followers` `/following` `/verified-followers`	Хора. Иска вход.
`/user/followers/you-know`	Последователи, които влезлият акаунт познава
`/user/subscriptions` `/subscribers`	Абонаменти и абонати

GET /users?screen_names=

До 20 профила, разделени със запетая.

GET /search?q=&product=

product е latest, top, people или media. Без вход: 401 login_required. Има cursor и count.

GET /search/communities?q=

Публикации от общности. Същите cursor и count.

GET /explore и GET /connect

Explore е смесена лента. Connect е хора, които X предлага на влезлия акаунт.

GET /suggest?q=

Подсказки: users, topics, hashtags.

GET /tweet/replies и GET /tweet/similar

Отговорите се страницират с cursor. Similar е празен, когато X няма подобни.

GET /account

Профилът, в който е влязъл облачният браузър. Без вход: 401 login_required.

Изтегляне

POST /info

Тяло {"url"}. Връща текста, автора, heights, has_video, has_photo, duration_seconds, media.

POST /jobs?wait=

Тяло {"url","mode","quality","bitrate"}. mode: video, mute, audio, photo. quality: max или височина като 720. bitrate е за MP3: 128, 192, 256, 320. wait (0–120) държи заявката, докато задачата свърши или времето изтече.

Състояния: queued, starting, downloading, processing, done, error, cancelled, expired.

GET /jobs · GET /jobs/{id} · DELETE /jobs/{id}

Само задачите на този ключ. Чужда задача е 404.

Файлът

GET /jobs/{id}/file иска ключ с право download. file.signed_url е GET /files/{token} и работи без ключ до expires_at (по подразбиране 60 минути). Медия се тегли само от video.twimg.com и pbs.twimg.com.

Система и администрация

GET /health — без ключ
GET /me — който и да е валиден ключ
GET /status — право status
GET и PATCH /settings — cookies_mode (fallback, always, never), cookies_source (agent, upload), data_source (auto, agent, anon). Няма проксита: данните излизат от IP-то на сървъра, а входът в акаунт е облачният браузър.
POST /routes/test, POST /routes/reset
PUT /cookies с тяло text/plain (Netscape cookies.txt), DELETE /cookies
POST /agent/refresh, /agent/import, /agent/logout

curl

curl -sS -H "Authorization: Bearer $XPK_KEY" \
  "https://x-api.kg-scripts.com/api/v1/tweet?id=20"