x-twitter-scraper 0.5.2 → 0.6.0

package/skills/x-twitter-scraper/references/api-endpoints-webhooks.md

@@ -0,0 +1,74 @@
+# Xquik REST API Endpoints: Webhooks
+
+### Create Webhook
+
+```
+POST /webhooks
+```
+
+**Body:**
+```json
+{
+  "url": "https://your-server.com/webhook",
+  "eventTypes": ["tweet.new", "tweet.reply"]
+}
+```
+
+**Response** includes a `secret` field (shown only once). Store it for signature verification.
+
+### List Webhooks
+
+```
+GET /webhooks
+```
+
+Returns all webhooks (up to 200). Secret is never exposed in list responses.
+
+### Update Webhook
+
+```
+PATCH /webhooks/{id}
+```
+
+**Body:** `{ "url": "...", "eventTypes": [...], "isActive": true|false }` (all optional)
+
+### Delete Webhook
+
+```
+delete request to `/webhooks/{id}`
+```
+
+Permanently removes the webhook. All future deliveries are stopped.
+
+### Test Webhook
+
+```
+POST /webhooks/{id}/test
+```
+
+Sends a `webhook.test` event to the webhook endpoint, HMAC-signed with the webhook's secret. Returns success or failure status with HTTP response details.
+
+**Payload delivered to your endpoint:**
+```json
+{
+  "eventType": "webhook.test",
+  "data": {
+    "message": "Test delivery from Xquik"
+  },
+  "timestamp": "2026-02-27T12:00:00.000Z"
+}
+```
+
+The delivery includes the `X-Xquik-Signature` header, identical to production deliveries.
+
+Returns `400 webhook_inactive` if the webhook is disabled. Reactivate via `PATCH /webhooks/{id}` before testing.
+
+### List Deliveries
+
+```
+GET /webhooks/{id}/deliveries
+```
+
+View delivery attempts and statuses for a webhook. Statuses: `pending`, `delivered`, `failed`, `exhausted`.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-x-accounts.md

@@ -0,0 +1,42 @@
+# Xquik REST API Endpoints: X Accounts (Connected)
+
+Manage connected X accounts for confirmation-gated write actions.
+
+**Connecting or re-authenticating an X account is done by the user in the Xquik dashboard**, not via this skill. The skill never handles X login material. The agent should direct the user to the dashboard account page when a new account needs to be connected or an existing session needs to be refreshed.
+
+The OpenAPI surface includes dashboard-owned account connection routes:
+
+```
+POST /x/accounts
+POST /x/account-connection-challenges/{id}/submit
+POST /x/accounts/{id}/reauth
+POST /x/accounts/bulk-retry
+```
+
+Do not call these from this skill. They are listed here only so the skill docs match the public API surface and keep the dashboard-only boundary explicit.
+
+### List X Accounts
+
+```
+GET /x/accounts
+```
+
+Returns all connected X accounts. Response: `{ accounts: [{ id, username, displayName, isActive, createdAt }] }`.
+
+### Get X Account
+
+```
+GET /x/accounts/{id}
+```
+
+Returns `{ id, username, displayName, isActive, createdAt }`.
+
+### Disconnect X Account
+
+```
+delete request to `/x/accounts/{id}`
+```
+
+Permanently removes the account from Xquik. Returns `{ success: true }`. Before calling, confirm with the user.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-x-api.md

@@ -0,0 +1,206 @@
+# Xquik REST API Endpoints: X API (Direct Lookups)
+
+Metered operations that require account access.
+
+### Get Tweet
+
+```
+GET /x/tweets/{id}
+```
+
+Returns full tweet with engagement metrics (likes, retweets, replies, quotes, views, bookmarks), author info (username, followers, verified status, profile picture), and optional attached media (photos/videos with URLs).
+
+### Get Article
+
+```
+GET /x/articles/{tweetId}
+```
+
+Retrieve the full content of an X Article (long-form post) by numeric tweet ID. If the user gives an article URL, use the final status ID as `tweetId`. Returns title, body text with block-level formatting, cover image, inline images, and engagement metrics. Metered.
+
+**Response:**
+```json
+{
+  "title": "Why AI Will Transform Everything",
+  "coverImage": "https://pbs.twimg.com/...",
+  "bodyHtml": "<p>The future of AI...</p>",
+  "likeCount": 5200,
+  "retweetCount": 890,
+  "replyCount": 245,
+  "viewCount": 150000,
+  "bookmarkCount": 1200,
+  "author": {
+    "id": "44196397",
+    "username": "elonmusk",
+    "name": "Elon Musk"
+  }
+}
+```
+
+### Search Tweets
+
+```
+GET /x/tweets/search?q={query}
+```
+
+Search using X syntax: keywords, `#hashtags`, `from:user`, `to:user`, `"exact phrases"`, `OR`, `-exclude`.
+
+Returns tweet info with optional engagement metrics (likeCount, retweetCount, replyCount) and optional attached media. Some fields may be omitted if unavailable.
+
+### Get User
+
+```
+GET /x/users/{id}
+```
+
+Returns profile info. `id` accepts either an X username without `@` or a numeric user ID. Fields `id`, `username`, `name` are always present. All other fields (`description`, `followers`, `following`, `verified`, `profilePicture`, `location`, `createdAt`, `statusesCount`) are optional and omitted when unavailable.
+
+### Batch & Search Users
+
+```
+GET /x/users/batch?ids=44196397,783214
+GET /x/users/search?q=founder
+```
+
+Batch lookup accepts up to 100 comma-separated numeric user IDs. User search returns matching profiles and may include a pagination cursor.
+
+### Check Follower
+
+```
+GET /x/followers/check?source={username}&target={username}
+```
+
+Returns `isFollowing` and `isFollowedBy` for both directions.
+
+### Get User Tweets
+
+```
+GET /x/users/{id}/tweets
+```
+
+Get a user's recent tweets by user ID. Metered per returned tweet.
+
+### Batch Tweets
+
+```
+GET /x/tweets?ids=1893456789012345678,1893456789012345679
+```
+
+Get multiple tweets by comma-separated tweet IDs. Maximum 100 IDs.
+
+### Get User Likes
+
+```
+GET /x/users/{id}/likes
+```
+
+Get tweets liked by a user. Metered per returned result.
+
+### Get User Media
+
+```
+GET /x/users/{id}/media
+```
+
+Get a user's media tweets (tweets containing photos/videos). Metered per returned result.
+
+### Get Tweet Favoriters
+
+```
+GET /x/tweets/{id}/favoriters
+```
+
+Get users who liked a tweet. Metered per returned result.
+
+### Tweet Conversation & Engagement Lists
+
+```
+GET /x/tweets/{id}/quotes
+GET /x/tweets/{id}/replies
+GET /x/tweets/{id}/retweeters
+GET /x/tweets/{id}/thread
+```
+
+Read quote tweets, replies, retweeters, or the conversation thread for a tweet. These are paginated read operations.
+
+### User Social Graph Reads
+
+```
+GET /x/users/{id}/followers
+GET /x/users/{id}/following
+GET /x/users/{id}/mentions
+GET /x/users/{id}/verified-followers
+```
+
+Read followers, following, mentions, and verified followers for a username or numeric user ID. These are paginated read operations.
+
+### Get Mutual Followers
+
+```
+GET /x/users/{id}/followers-you-know
+```
+
+Get mutual followers (followers you know). Metered per returned result.
+
+### X Lists
+
+```
+GET /x/lists/{id}/followers
+GET /x/lists/{id}/members
+GET /x/lists/{id}/tweets
+```
+
+Read list followers, members, or list timeline tweets by list ID.
+
+### X Communities
+
+```
+GET /x/communities/search
+GET /x/communities/tweets
+GET /x/communities/{id}/info
+GET /x/communities/{id}/members
+GET /x/communities/{id}/moderators
+GET /x/communities/{id}/tweets
+```
+
+Search communities and read community metadata, members, moderators, or tweets. Community writes are listed under X Write and require confirmation.
+
+### Get Bookmarks
+
+```
+GET /x/bookmarks
+```
+
+Get bookmarked tweets. Requires a connected X account. Metered per returned result.
+
+**Sensitive:** Returns private data. Confirm with user before calling.
+
+### Get Bookmark Folders
+
+```
+GET /x/bookmarks/folders
+```
+
+Get bookmark folders. Requires a connected X account. Metered.
+
+### Get Notifications
+
+```
+GET /x/notifications
+```
+
+Get notifications with type filter. Requires a connected X account. Metered per returned result.
+
+**Sensitive:** Returns private data. Confirm with user before calling.
+
+### Get Home Timeline
+
+```
+GET /x/timeline
+```
+
+Get home timeline. Requires a connected X account. Metered per returned result.
+
+**Sensitive:** Returns private data. Confirm with user before calling.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-x-media.md

@@ -0,0 +1,40 @@
+# Xquik REST API Endpoints: X Media (Download)
+
+### Download Media
+
+```
+POST /x/media/download
+```
+
+Download images, videos, and GIFs from tweets. Single or bulk (up to 50). Returns a shareable gallery URL.
+
+**Body:** Provide either `tweetInput` (single tweet) or `tweetIds` (bulk). Exactly 1 is required.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tweetInput` | string | Tweet URL or numeric tweet ID for a single download. Accepts `x.com` and `twitter.com` URL formats |
+| `tweetIds` | string[] | Array of tweet URLs or IDs for bulk download. Maximum 50 items. Returns a single combined gallery |
+
+**Response (single):**
+```json
+{
+  "tweetId": "1893456789012345678",
+  "galleryUrl": "https://xquik.com/g/abc123",
+  "cacheHit": false
+}
+```
+
+**Response (bulk):**
+```json
+{
+  "galleryUrl": "https://xquik.com/g/def456",
+  "totalTweets": 3,
+  "totalMedia": 7
+}
+```
+
+First download is metered. Subsequent requests for the same tweet return cached URLs when `cacheHit: true`. All downloads are saved to shareable gallery pages under `https://xquik.com/g/{token}`.
+
+Returns `400 no_media` if the tweet has no downloadable media. Returns `400 too_many_tweets` if bulk array exceeds 50 items.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints-x-write.md

@@ -0,0 +1,204 @@
+# Xquik REST API Endpoints: X Write
+
+Write actions performed through connected X accounts. All endpoints are metered. Every request requires an `account` field (username or account ID) identifying which connected account to use.
+
+### Create Tweet
+
+```
+POST /x/tweets
+```
+
+**Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `account` | string | Yes | Connected X username or account ID |
+| `text` | string | No | Tweet text (280 chars, or 25,000 if `is_note_tweet` is true). Required unless `media` is provided |
+| `reply_to_tweet_id` | string | No | Tweet ID to reply to |
+| `attachment_url` | string | No | URL to attach as a card |
+| `community_id` | string | No | Community ID to post into |
+| `is_note_tweet` | boolean | No | Long-form note tweet (up to 25,000 chars) |
+| `media` | string[] | No | Public image URLs to attach (max 4). `POST /x/media` returns `mediaUrl` values for this field |
+
+**Response:** `{ tweetId, success: true }`
+
+**Errors:** `502 x_write_failed`
+
+### Delete Tweet
+
+```
+delete request to `/x/tweets/{id}`
+```
+
+**Body:** `{ "account": "username" }`
+
+**Response:** `{ success: true }`
+
+### Like Tweet
+
+```
+POST /x/tweets/{id}/like
+```
+
+**Body:** `{ "account": "username" }`
+
+### Unlike Tweet
+
+```
+delete request to `/x/tweets/{id}/like`
+```
+
+**Body:** `{ "account": "username" }`
+
+### Retweet
+
+```
+POST /x/tweets/{id}/retweet
+```
+
+**Body:** `{ "account": "username" }`
+
+### Unretweet
+
+```
+delete request to `/x/tweets/{id}/retweet`
+```
+
+**Body:** `{ "account": "username" }`
+
+### Follow User
+
+```
+POST /x/users/{id}/follow
+```
+
+**Body:** `{ "account": "username" }`
+
+**Errors:** `502 x_write_failed`
+
+### Unfollow User
+
+```
+delete request to `/x/users/{id}/follow`
+```
+
+**Body:** `{ "account": "username" }`
+
+### Remove Follower
+
+```
+POST /x/users/{id}/remove-follower
+```
+
+Remove a user from your followers without blocking them.
+
+**Body:** `{ "account": "username" }`
+
+**Usage:** Metered per call.
+
+### Send DM
+
+```
+POST /x/dm/{userId}
+```
+
+**Body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `account` | string | Yes | Connected X username or account ID |
+| `text` | string | Yes | Message text |
+| `media_ids` | string[] | No | Media IDs to attach |
+| `reply_to_message_id` | string | No | Message ID to reply to |
+
+### Get DM History
+
+```
+GET /x/dm/{userId}/history
+```
+
+Get DM conversation history with a user. Requires a connected X account. Metered per returned result.
+
+**Sensitive:** Returns private DM conversations. Confirm with user before calling. Forward to other tools only after explicit approval.
+
+### Update Profile
+
+```
+PATCH /x/profile
+```
+
+**Body:** `{ "account": "username", "name": "...", "description": "...", "location": "...", "url": "..." }` (account required, others optional)
+
+### Update Avatar
+
+```
+PATCH /x/profile/avatar
+```
+
+Update profile avatar. Max 700 KB, GIF/JPEG/PNG. Metered.
+
+**Body:** FormData with `account` (required) and `file` (required, max 700 KB).
+
+### Update Banner
+
+```
+PATCH /x/profile/banner
+```
+
+Update profile banner. Max 2 MB, GIF/JPEG/PNG. Metered.
+
+**Body:** FormData with `account` (required) and `file` (required, max 2 MB).
+
+### Upload Media
+
+```
+POST /x/media
+```
+
+**Body:** FormData with `account` (required), `file` (required), and `is_long_video` (optional boolean). Alternatively, JSON body with `account` (required) and `url` (required, direct media URL) for URL-based upload.
+
+**Response:** Returns `mediaId`, `mediaUrl`, and `success`. Pass `mediaUrl` in the `media` array when creating a tweet.
+
+### Create Community
+
+```
+POST /x/communities
+```
+
+**Body:** `{ "account": "username", "name": "...", "description": "..." }` (all required)
+
+### Delete Community
+
+```
+delete request to `/x/communities/{id}`
+```
+
+**Body:** `{ "account": "username", "community_name": "..." }` (name required for confirmation)
+
+### Join Community
+
+```
+POST /x/communities/{id}/join
+```
+
+**Body:** `{ "account": "username" }`
+
+**Errors:** `409 already_member`
+
+### Leave Community
+
+```
+delete request to `/x/communities/{id}/join`
+```
+
+**Body:** `{ "account": "username" }`
+
+### Get Write Action Status
+
+```
+GET /x/write-actions/{id}
+```
+
+Check a pending write action by the ID returned from an earlier write response.
+
+---

package/skills/x-twitter-scraper/references/api-endpoints.md

@@ -0,0 +1,30 @@
+# Xquik REST API Endpoints
+
+Routing index for the REST API reference. Load only the section file needed for the user task instead of loading the full endpoint catalog.
+
+Base URL: `https://xquik.com/api/v1`
+
+All requests require the `x-api-key` header unless the section says session auth only. All responses are JSON. HTTPS only.
+
+Plan and credit changes are dashboard-only. Agents may read usage state with `GET /credits`, but must not start plan or credit changes.
+
+| Need | Reference |
+|---|---|
+| API Keys | [api-keys.md](api-endpoints-api-keys.md) |
+| Monitors | [monitors.md](api-endpoints-monitors.md) |
+| Events | [events.md](api-endpoints-events.md) |
+| Webhooks | [webhooks.md](api-endpoints-webhooks.md) |
+| Draws | [draws.md](api-endpoints-draws.md) |
+| Extractions | [extractions.md](api-endpoints-extractions.md) |
+| X API (Direct Lookups) | [x-api.md](api-endpoints-x-api.md) |
+| X Media (Download) | [x-media.md](api-endpoints-x-media.md) |
+| Trends | [trends.md](api-endpoints-trends.md) |
+| Radar | [radar.md](api-endpoints-radar.md) |
+| Compose | [compose.md](api-endpoints-compose.md) |
+| Drafts | [drafts.md](api-endpoints-drafts.md) |
+| Tweet Style Cache | [tweet-style-cache.md](api-endpoints-tweet-style-cache.md) |
+| X Accounts (Connected) | [x-accounts.md](api-endpoints-x-accounts.md) |
+| X Write | [x-write.md](api-endpoints-x-write.md) |
+| Credits | [credits.md](api-endpoints-credits.md) |
+| Support | [support.md](api-endpoints-support.md) |
+| Error Codes | [error-codes.md](api-endpoints-error-codes.md) |

package/skills/x-twitter-scraper/references/draws.md

@@ -0,0 +1,57 @@
+# Xquik Giveaway Draws
+
+Run transparent, auditable giveaway draws from tweet replies with configurable filters.
+
+## Create Draw
+
+`POST /draws` with a `tweetUrl` (required) and optional filters:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `tweetUrl` | string | **Required.** Full tweet URL: `https://x.com/user/status/ID` |
+| `winnerCount` | number | Winners to select (default 1) |
+| `backupCount` | number | Backup winners to select |
+| `uniqueAuthorsOnly` | boolean | Count only one entry per author |
+| `mustRetweet` | boolean | Require participants to have retweeted |
+| `mustFollowUsername` | string | Username participants must follow |
+| `filterMinFollowers` | number | Minimum follower count |
+| `filterAccountAgeDays` | number | Minimum account age in days |
+| `filterLanguage` | string | Language code (e.g., `"en"`) |
+| `requiredKeywords` | string[] | Words that must appear in the reply |
+| `requiredHashtags` | string[] | Hashtags that must appear (e.g., `["#giveaway"]`) |
+| `requiredMentions` | string[] | Usernames that must be mentioned (e.g., `["@xquik"]`) |
+
+## Complete Workflow
+
+```javascript
+// Step 1: Create draw with filters
+const draw = await xquikFetch("/draws", {
+  method: "POST",
+  body: JSON.stringify({
+    tweetUrl: "https://x.com/burakbayir/status/1893456789012345678",
+    winnerCount: 3,
+    backupCount: 2,
+    uniqueAuthorsOnly: true,
+    mustRetweet: true,
+    mustFollowUsername: "burakbayir",
+    filterMinFollowers: 50,
+    filterAccountAgeDays: 30,
+    filterLanguage: "en",
+    requiredHashtags: ["#giveaway"],
+  }),
+});
+
+// Step 2: Get draw details with winners
+const details = await xquikFetch(`/draws/${draw.id}`);
+// details.winners: [
+//   { position: 1, authorUsername: "winner1", tweetId: "...", isBackup: false },
+//   ...
+// ]
+
+// Step 3: Export results
+const exportUrl = `${BASE}/draws/${draw.id}/export?format=csv`;
+```
+
+## Usage
+
+Metered per participant entry.