twitter-developer-api 2.5.3

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.

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

@@ -0,0 +1,237 @@
+# Xquik Extraction Tools
+
+23 bulk data extraction tools. Each requires a specific target parameter.
+
+**Endpoint:** `POST /extractions`
+
+**Always estimate first:** `POST /extractions/estimate` with the same body to preview `creditsRequired`, `creditsAvailable`, and whether the job is allowed.
+
+## Contents
+
+- [Tool Types](#tool-types)
+- [Response](#response)
+- [Retrieving Results](#retrieving-results)
+- [Exporting Results](#exporting-results)
+- [Estimating Usage](#estimating-usage)
+
+## Tool Types
+
+### Tweet-Based (require `targetTweetId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `reply_extractor` | Extract users who replied to a tweet |
+| `repost_extractor` | Extract users who retweeted a tweet |
+| `quote_extractor` | Extract users who quote-tweeted a tweet |
+| `thread_extractor` | Extract all tweets in a thread |
+| `article_extractor` | Extract article content linked in a tweet |
+| `favoriters` | Extract users who favorited a tweet |
+
+**Example:**
+```json
+{
+  "toolType": "reply_extractor",
+  "targetTweetId": "1893704267862470862"
+}
+```
+
+### User-Based (require `targetUsername`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `follower_explorer` | Extract followers of an account |
+| `following_explorer` | Extract accounts followed by a user |
+| `verified_follower_explorer` | Extract verified followers of an account |
+| `mention_extractor` | Extract tweets mentioning an account |
+| `post_extractor` | Extract posts from an account |
+
+**Example:**
+```json
+{
+  "toolType": "follower_explorer",
+  "targetUsername": "elonmusk"
+}
+```
+
+The `@` prefix is automatically stripped if included.
+
+### User-Based by ID (require `targetUserId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `user_likes` | Extract tweets liked by a user |
+| `user_media` | Extract media tweets from a user |
+
+**Example:**
+```json
+{
+  "toolType": "user_likes",
+  "targetUserId": "44196397"
+}
+```
+
+### Community-Based (require `targetCommunityId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `community_extractor` | Extract members of a community |
+| `community_moderator_explorer` | Extract moderators of a community |
+| `community_post_extractor` | Extract posts from a community |
+| `community_search` | Search posts within a community (also requires `searchQuery`) |
+
+**Example:**
+```json
+{
+  "toolType": "community_extractor",
+  "targetCommunityId": "1234567890"
+}
+```
+
+### List-Based (require `targetListId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `list_member_extractor` | Extract members of a list |
+| `list_post_extractor` | Extract posts from a list |
+| `list_follower_explorer` | Extract followers of a list |
+
+**Example:**
+```json
+{
+  "toolType": "list_member_extractor",
+  "targetListId": "1234567890"
+}
+```
+
+### Space-Based (require `targetSpaceId`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `space_explorer` | Extract participants of a Space |
+
+**Example:**
+```json
+{
+  "toolType": "space_explorer",
+  "targetSpaceId": "1YqKDqDXAbwKV"
+}
+```
+
+### Search-Based (require `searchQuery`)
+
+| Tool Type | Description |
+|-----------|-------------|
+| `people_search` | Search for users by keyword |
+| `tweet_search_extractor` | Search and extract tweets by keyword or hashtag (bulk, up to 1,000) |
+
+**Example (people search):**
+```json
+{
+  "toolType": "people_search",
+  "searchQuery": "machine learning engineer"
+}
+```
+
+**Example (tweet search):**
+```json
+{
+  "toolType": "tweet_search_extractor",
+  "searchQuery": "#AI",
+  "resultsLimit": 100
+}
+```
+
+### Tweet Search Filters
+
+The `tweet_search_extractor` tool type supports 16 additional filter fields that are converted to X search operators and combined with `searchQuery`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `fromUser` | string | Author username |
+| `toUser` | string | Directed to user |
+| `mentioning` | string | Mentions user |
+| `language` | string | Language code (e.g., `en`) |
+| `sinceDate` | string | Start date (YYYY-MM-DD) |
+| `untilDate` | string | End date (YYYY-MM-DD) |
+| `mediaType` | string | `images`, `videos`, `gifs`, or `media` |
+| `minFaves` | number | Minimum likes |
+| `minRetweets` | number | Minimum retweets |
+| `minReplies` | number | Minimum replies |
+| `verifiedOnly` | boolean | Verified authors only |
+| `replies` | string | `include`, `exclude`, or `only` |
+| `retweets` | string | `include`, `exclude`, or `only` |
+| `exactPhrase` | string | Exact match text |
+| `excludeWords` | string | Comma-separated words to exclude |
+| `advancedQuery` | string | Raw X search operators appended to query |
+
+**Example with filters:**
+```json
+{
+  "toolType": "tweet_search_extractor",
+  "searchQuery": "AI",
+  "fromUser": "elonmusk",
+  "minFaves": 100,
+  "sinceDate": "2026-01-01",
+  "mediaType": "videos",
+  "resultsLimit": 500
+}
+```
+
+`resultsLimit` (optional): Maximum results to extract. Stops early instead of fetching all. Pass this on both `POST /extractions/estimate` and `POST /extractions` when you only need a specific count.
+
+## Response
+
+```json
+{
+  "id": "77777",
+  "toolType": "reply_extractor",
+  "status": "completed",
+  "totalResults": 150
+}
+```
+
+Statuses: `pending`, `running`, `completed`, `failed`.
+
+## Retrieving Results
+
+```
+GET /extractions/{id}
+```
+
+Returns paginated results (up to 1,000 per page). Each result includes:
+
+- `xUserId`, `xUsername`, `xDisplayName`
+- `xFollowersCount`, `xVerified`, `xProfileImageUrl`
+- `tweetId`, `tweetText`, `tweetCreatedAt` (for tweet-based extractions)
+
+## Exporting Results
+
+```
+GET /extractions/{id}/export?format=csv
+```
+
+Formats: `csv`, `json`, `md`, `md-document`, `pdf`, `txt`, `xlsx`. 100,000 row limit (10,000 for PDF).
+
+Exports include enrichment columns not present in the API response.
+
+## Estimating Usage
+
+```
+POST /extractions/estimate
+```
+
+Same body as create. Response:
+
+```json
+{
+  "allowed": true,
+  "source": "replyCount",
+  "estimatedResults": 150,
+  "creditsRequired": "150",
+  "creditsAvailable": "50000"
+}
+```
+
+If `allowed` is `false`, the extraction requires more credits than are currently available.
+
+For common mistakes and tool selection rules, see [mcp-tools.md](mcp-tools.md#common-mistakes).