From bbedf2d195bf29fcdd43342c0cce1cf626e2a750 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Wed, 11 Mar 2026 15:28:00 -0700 Subject: [PATCH 1/6] Add developer guidelines --- developer-guidelines.mdx | 402 +++++++++++++++++++++++++++++++++++++++ docs.json | 11 +- 2 files changed, 405 insertions(+), 8 deletions(-) create mode 100644 developer-guidelines.mdx diff --git a/developer-guidelines.mdx b/developer-guidelines.mdx new file mode 100644 index 00000000..b3e30e89 --- /dev/null +++ b/developer-guidelines.mdx @@ -0,0 +1,402 @@ +--- +title: "Developer Guidelines" +sidebarTitle: "Developer Guidelines" +description: "A practical guide to what's allowed and what's not when building with the X API." +icon: "scale-balanced" +--- + + + **Violations can result in app suspension, API access revocation, or permanent account bans.** Always review the official policies before building. + + + + + Binding legal terms for API access + + + Rules for building on X + + + Specific rules for bots + + + Prohibited activities + + + +--- + +## Quick Check: Is My Bot/App Allowed? + +Before building, ask yourself these questions. If you answer **"no"** to any of them, your app likely violates X's policies. + + + + Did the user **explicitly request** this interaction? + + + Is it **clearly labeled as a bot** (profile label + bio disclosure)? + + + Can users **easily opt out** of interactions? + + + Does it provide **real value** beyond self-promotion? + + + Are you **only using the official API** (not scraping/browser automation)? + + + Are you **within rate limits** and not trying to circumvent them? + + + + + When in doubt, ask: "Would a user be happy to receive this interaction?" If not, don't automate it. + + +--- + +## Common Scenarios: Allowed or Not? + +Real-world examples to help you understand what's permitted. + + + + | Scenario | Allowed? | Why | + |----------|:--------:|-----| + | Bot posts scheduled content (news, weather, quotes) | ✅ | Informational, no unsolicited mentions | + | Bot posts RSS feed updates automatically | ✅ | Helpful broadcasting | + | Bot posts earthquake/disaster alerts | ✅ | Public safety value | + | Bot posts sports scores or game updates | ✅ | Informational | + | Bot posts stock/crypto prices on schedule | ✅ | Informational, no manipulation | + | Bot posts identical content across multiple accounts | ❌ | Spam / platform manipulation | + | Bot posts to trending topics to gain visibility | ❌ | Trend manipulation | + | Multiple city-specific weather bots (e.g., @WeatherNYC, @WeatherLA) | ✅ | Allowed—non-duplicative, location-specific content | + + + | Scenario | Allowed? | Why | + |----------|:--------:|-----| + | Bot responds to @mentions asking for help | ✅ | User-initiated request | + | Bot replies to anyone mentioning a keyword | ❌ | Unsolicited interaction | + | Bot auto-replies to users who reply to your tweet | ✅* | User engaged first—limit 1 reply per interaction | + | AI-powered bot generates and posts replies | ⚠️ | Requires **prior approval** from X | + | Bot replies with "follow me for more!" to random users | ❌ | Spam, unsolicited | + | Thread unroller bot that responds when asked | ✅ | User-initiated utility | + + *Conditional—see [Gray Areas](#gray-areas-explained) section below. + + + | Scenario | Allowed? | Why | + |----------|:--------:|-----| + | Bot responds to DMs with helpful info | ✅ | User-initiated | + | Bot sends affiliate links when user DMs first | ✅* | User-initiated—must disclose affiliate relationship | + | Bot auto-DMs new followers with welcome message | ❌ | Unsolicited, even to followers | + | Bot bulk-DMs users about a product launch | ❌ | Spam | + | Support bot asks "How can I help?" after user DMs | ✅ | User-initiated conversation | + + *Conditional—see [Gray Areas](#gray-areas-explained) section below. + + + | Scenario | Allowed? | Why | + |----------|:--------:|-----| + | Bot auto-likes posts containing a hashtag | ❌ | Automated likes banned | + | Bot auto-likes posts from a specific user | ❌ | Automated likes banned | + | Bot reposts content from a curated list | ✅* | OK for informational purposes, no bulk spam | + | Bot bulk-follows accounts to grow audience | ❌ | Manipulation | + | Bot follows back anyone who follows it | ❌ | Bulk/aggressive following | + | Bot adds users to lists in bulk | ❌ | Indiscriminate list manipulation | + + **Automated likes are banned with no exceptions.** This is one of the most common violations. + + + | Scenario | Allowed? | Why | + |----------|:--------:|-----| + | Bot sends product recommendations when asked | ✅ | User-initiated | + | Bot replies to random posts with affiliate links | ❌ | Unsolicited spam | + | Giveaway bot that requires follows/retweets to enter | ⚠️ | Risky—can be seen as engagement manipulation | + | Bot selling likes/follows/retweets | ❌ | Strictly prohibited | + | Tip bot that sends crypto when user requests | ✅* | User-initiated—comply with financial regulations | + + *Conditional—see [Gray Areas](#gray-areas-explained) section below. + + + | Scenario | Allowed? | Why | + |----------|:--------:|-----| + | App tracks brand mentions for analytics dashboard | ✅ | Valid use case | + | App scrapes X via browser automation (not API) | ❌ | **Permanent suspension**—API only | + | App stores X data to train AI/ML models | ❌ | Prohibited (except Grok) | + | App redistributes >1.5M posts in 30 days | ❌ | Exceeds redistribution limits | + | App benchmarks X performance vs competitors | ❌ | Prohibited competitive analysis | + | Academic research on public conversation trends | ✅ | Valid with proper data handling | + + + **Non-API automation (scraping, browser automation) results in permanent suspension.** Always use the official X API. + + + + +--- + +## Prohibited Activities + + + These activities will get your app suspended or permanently banned. There are no exceptions. + + +| Category | Examples | +|----------|----------| +| **Spam & Manipulation** | Identical content across accounts, fake engagement, trend manipulation, bulk posting | +| **Unsolicited Outreach** | Auto-replies to random users, bulk DMs, uninvited @mentions | +| **Deceptive Bots** | Impersonating humans, hiding bot identity, misleading links/redirects | +| **Engagement Selling** | Apps that sell likes, follows, retweets, or views | +| **Rate Limit Abuse** | Exceeding limits, designing apps that encourage overuse | +| **Non-API Automation** | Browser scripting, scraping, any automation outside official API | +| **Account Farms** | Multiple accounts for same duplicative purpose | +| **Surveillance** | Profiling, tracking, or monitoring users without consent | +| **Unauthorized AI Training** | Using X data to train ML models (Grok excepted) | +| **Sensitive Data Derivation** | Inferring health, political, religious, or other sensitive attributes | +| **Excessive Redistribution** | Sharing >1.5M Post IDs per 30-day period | + +--- + +## Automation Rules + +### Requirements for All Bots + +All automated accounts using the X API must meet these requirements: + + + + This label appears under your bot's name/handle on its profile. Enable it in your app settings to ensure transparency. + + + State clearly that it's a bot and who operates it. Example: *"Bot by @yourcompany"* or *"Automated account managed by Example Inc."* + + + For accountability and contact purposes, your bot must be associated with a human-managed account. + + + If a user says "stop," stop. Implement keyword detection for common opt-out phrases. + + + No scraping, browser automation, or unofficial methods. Violations result in permanent suspension. + + + Don't try to circumvent or abuse rate limits. Design your app to handle limits gracefully. + + + +### What Can Bots Do? + +| Action | Allowed? | Rules | +|--------|:--------:|-------| +| **Post tweets** | ✅ | No unsolicited @mentions. No identical cross-posting. | +| **Reply to users** | ⚠️ | Only if user engaged first. Max **1 reply per interaction**. | +| **Send DMs** | ⚠️ | Only after user DMs you first. Easy opt-out required. | +| **Like posts** | ❌ | **Automated likes are banned.** No exceptions. | +| **Repost** | ⚠️ | OK for informational/entertainment. No bulk spam. | +| **Quote tweet** | ⚠️ | Same rules as repost—no spam or manipulation. | +| **Follow/Unfollow** | ❌ | No bulk, aggressive, or automated following. | +| **Add to Lists** | ⚠️ | No bulk or indiscriminate additions. | +| **Bookmark** | ✅ | Fine for personal/automated use. | +| **Search/Read** | ✅ | Standard use within rate limits. | + +--- + +## Gray Areas Explained + +Many developers have questions about edge cases. Here's guidance on common gray areas. + + + + + **Allowed if:** + - User explicitly requests it (e.g., DMs asking for a recommendation) + - You clearly disclose the affiliate/sponsored relationship + - Links are not misleading (no deceptive redirects) + + + + **Not allowed if:** + - You auto-reply to random posts with affiliate links + - You DM users who didn't ask + - You hide the commercial relationship + + + + + - **Requires prior approval from X** before deployment + - Must still follow all rules (no unsolicited mentions, properly labeled) + - Contact [X Developer Support](https://docs.x.com/support) before launching + - Even with approval, cannot impersonate humans + + Deploying AI-generated replies without approval is a violation, even if the content itself is helpful. + + + + **Not allowed** as automated DMs—this counts as unsolicited contact, even though they followed you. + + **Alternatives:** + - Pinned tweet welcoming new followers + - Bio with intro info and links + - Auto-reply only if they DM you first + + + + + **Allowed if:** + - Each account serves **non-duplicative** purposes (e.g., @EarthquakeJP, @EarthquakeCA) + - Content is meaningfully different (location-specific, language-specific) + - Not used to bypass limits or amplify the same message + + + + **Not allowed if:** + - Posting identical/similar content across accounts + - Created to evade suspensions or rate limits + + + + + + **Allowed if:** + - User initiates (mentions you, DMs you, or explicitly opts in) + - Clear opt-out mechanism exists + - Responses are helpful, not promotional + - Includes privacy policy link in DMs + + + + **Not allowed if:** + - You reach out to users who complained publicly (unsolicited) + - Responses are primarily promotional + + + + + **Proceed with caution:** + - Requiring follows/retweets as entry can be seen as engagement manipulation + - Must comply with [X's contest guidelines](https://help.x.com/en/rules-and-policies/x-contest-rules) + - Don't use multiple accounts to amplify + - Ensure prizes are real and delivered + + Consider entry methods that don't require engagement actions, like replying with a specific phrase. + + + + + **Allowed if:** + - Clearly labeled as parody/novelty in bio and name + - Doesn't impersonate in a misleading way + - Still follows all bot labeling requirements if automated + + + + + + **Allowed:** + - Price alerts, weather warnings, earthquake notifications, flight status + - Must be informational, not promotional + - User should have opted in or requested alerts + - Public safety alerts have more latitude + + + + + **Special requirements:** + - Must mark account as **sensitive** in settings + - Must comply with X's [sensitive media policy](https://help.x.com/en/rules-and-policies/media-policy) + - No unsolicited adult content in replies/DMs + + Failure to properly label sensitive content is a violation. + + + +--- + +## Valid Use Cases & Bot Examples + +Looking for inspiration? Here are categories of bots and apps that align with X's policies: + + + + RSS feed bots, breaking news alerts, sports scores, weather updates + + + Earthquake alerts, disaster warnings, emergency notifications + + + Thread unrollers, translation bots, accessibility helpers, URL expanders + + + Help desk bots (user-initiated), FAQ responders, ticket status + + + Trivia bots (opt-in), daily quotes, meme accounts, novelty/parody + + + Stock/crypto price bots, earnings alerts, market news (informational only) + + + GitHub commit notifications, CI/CD status, deployment alerts + + + Event reminders, meetup announcements, community updates + + + Sentiment dashboards, trend monitoring, brand tracking + + + Image description bots, alt-text generators (when requested) + + + +--- + +## Technical Restrictions + + + These limits apply to all developers. Exceeding them can result in rate limiting or suspension. + + +| Restriction | Limit | +|-------------|-------| +| **Content redistribution** | Max 1.5M Post IDs per 30-day period | +| **Rate limits** | Vary by endpoint and tier—[see API docs](/x-api/rate-limits) | +| **AI/ML training** | Prohibited (except for Grok) | +| **Non-API access** | Prohibited—scraping and browser automation = permanent ban | +| **Competitive benchmarking** | Prohibited—can't measure X performance for competitive analysis | + +--- + +## Summary: Do's and Don'ts + + + + - Enable "Automated" profile label + - Disclose bot operator in bio + - Wait for users to initiate interaction + - Provide easy opt-out + - Disclose affiliate/sponsored relationships + - Respect rate limits + - Use only the official X API + - Get approval for AI-generated replies + - Create non-duplicative regional accounts + - Mark sensitive content appropriately + - Stay within redistribution limits + + + - Hide that it's a bot + - Impersonate humans + - Send unsolicited DMs, replies, or @mentions + - Ignore "stop" requests + - Use misleading links or hidden promotions + - Try to circumvent limits or scrape + - Use browser automation or scraping + - Deploy AI replies without approval + - Post identical content across accounts + - Post adult content without proper labels + - Redistribute >1.5M posts/30 days + + diff --git a/docs.json b/docs.json index ec058344..7c654676 100644 --- a/docs.json +++ b/docs.json @@ -1037,17 +1037,12 @@ ] }, { - "tab": "Use Cases", + "tab": "Guidelines", "groups": [ { - "group": "Build for businesses", + "group": "Guidelines", "pages": [ - "use-cases/build-for-business", - "use-cases/build-for-consumers", - "use-cases/do-research", - "use-cases/teach-and-learn", - "use-cases/build-for-good", - "use-cases/build-for-fun" + "developer-guidelines" ] } ] From c639f4f78033c99b9829e7a8408d7aa4160003df Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Wed, 11 Mar 2026 16:51:48 -0700 Subject: [PATCH 2/6] Add Developer Guidelines --- developer-guidelines.mdx | 241 ++++++++++++++++++++++++--------------- 1 file changed, 152 insertions(+), 89 deletions(-) diff --git a/developer-guidelines.mdx b/developer-guidelines.mdx index b3e30e89..84d6eef9 100644 --- a/developer-guidelines.mdx +++ b/developer-guidelines.mdx @@ -26,19 +26,19 @@ icon: "scale-balanced" --- -## Quick Check: Is My Bot/App Allowed? +## Quick Check: Is My App Allowed? Before building, ask yourself these questions. If you answer **"no"** to any of them, your app likely violates X's policies. - Did the user **explicitly request** this interaction? + For interactions, did the user **explicitly request** it? - - Is it **clearly labeled as a bot** (profile label + bio disclosure)? + + Is your app's purpose and behavior **clear to users**? (Automated accounts must be labeled.) - Can users **easily opt out** of interactions? + Can users **easily opt out** of any ongoing interactions? Does it provide **real value** beyond self-promotion? @@ -47,19 +47,19 @@ Before building, ask yourself these questions. If you answer **"no"** to any of Are you **only using the official API** (not scraping/browser automation)? - Are you **within rate limits** and not trying to circumvent them? + Are you **within rate limits** and respecting usage policies? - When in doubt, ask: "Would a user be happy to receive this interaction?" If not, don't automate it. + When in doubt, ask: "Would a user be happy with this experience?" If not, reconsider your approach. --- ## Common Scenarios: Allowed or Not? -Real-world examples to help you understand what's permitted. +Real-world examples to help you understand what's permitted. These cover automated accounts, integrations, and apps of all types. @@ -162,7 +162,11 @@ Real-world examples to help you understand what's permitted. ## Automation Rules -### Requirements for All Bots + + This section applies specifically to **automated accounts** (bots) that post, reply, or interact on behalf of users. If you're building an analytics dashboard, research tool, or other non-automated app, these labeling requirements don't apply to you—but the technical restrictions still do. + + +### Requirements for Automated Accounts All automated accounts using the X API must meet these requirements: @@ -187,7 +191,7 @@ All automated accounts using the X API must meet these requirements: -### What Can Bots Do? +### Automated Actions: What's Allowed? | Action | Allowed? | Rules | |--------|:--------:|-------| @@ -258,7 +262,7 @@ Many developers have questions about edge cases. Here's guidance on common gray - + **Allowed if:** - User initiates (mentions you, DMs you, or explicitly opts in) @@ -274,7 +278,7 @@ Many developers have questions about edge cases. Here's guidance on common gray - + **Proceed with caution:** - Requiring follows/retweets as entry can be seen as engagement manipulation - Must comply with [X's contest guidelines](https://help.x.com/en/rules-and-policies/x-contest-rules) @@ -283,74 +287,79 @@ Many developers have questions about edge cases. Here's guidance on common gray Consider entry methods that don't require engagement actions, like replying with a specific phrase. + - - - **Allowed if:** - - Clearly labeled as parody/novelty in bio and name - - Doesn't impersonate in a misleading way - - Still follows all bot labeling requirements if automated - - +--- - - - **Allowed:** - - Price alerts, weather warnings, earthquake notifications, flight status - - Must be informational, not promotional - - User should have opted in or requested alerts - - Public safety alerts have more latitude - - +## Data Handling & Display Requirements - - **Special requirements:** - - Must mark account as **sensitive** in settings - - Must comply with X's [sensitive media policy](https://help.x.com/en/rules-and-policies/media-policy) - - No unsolicited adult content in replies/DMs + + These requirements are legally binding under the Developer Agreement. Non-compliance can result in termination and legal action. + - Failure to properly label sensitive content is a violation. - - +### Content Deletion ---- +You must delete X Content from your systems when requested: -## Valid Use Cases & Bot Examples +| Trigger | Deadline | +|---------|----------| +| X requests deletion | **24 hours** | +| User requests deletion | **24 hours** | +| Content is suspended/removed on X | **24 hours** | +| Your API access is terminated | **10 business days** (must delete all X data) | -Looking for inspiration? Here are categories of bots and apps that align with X's policies: + + Use [Compliance Firehose](https://docs.x.com/x-api/compliance/streams) to receive real-time deletion events and stay compliant automatically. + - - - RSS feed bots, breaking news alerts, sports scores, weather updates - - - Earthquake alerts, disaster warnings, emergency notifications - - - Thread unrollers, translation bots, accessibility helpers, URL expanders - - - Help desk bots (user-initiated), FAQ responders, ticket status - - - Trivia bots (opt-in), daily quotes, meme accounts, novelty/parody - - - Stock/crypto price bots, earnings alerts, market news (informational only) - - - GitHub commit notifications, CI/CD status, deployment alerts - - - Event reminders, meetup announcements, community updates - - - Sentiment dashboards, trend monitoring, brand tracking - - - Image description bots, alt-text generators (when requested) - - +### Off-X Matching + +**Off-X matching** means associating X data (username, user ID, posts) with off-platform identifiers (your customer database, email lists, device IDs, etc.). + + + **Allowed with express opt-in consent:** + - User explicitly agrees to link their X account with your service + - Clear disclosure of what data will be matched and why + + + + **Without consent, you may only match:** + - Information the user directly provided to you + - Publicly available X data (posts, bio, display name, username) + - Public resources like professional directories + + **Never match if it would surprise the user.** + + +### Sensitive Data + + + You **cannot** derive, infer, or store information about X users in these categories: + + +| Category | Examples | +|----------|----------| +| **Health** | Medical conditions, pregnancy, disabilities | +| **Financial status** | Negative financial condition, credit issues | +| **Political** | Party affiliation, political beliefs, voting | +| **Racial/Ethnic** | Origin, ethnicity | +| **Religious/Philosophical** | Beliefs, affiliations | +| **Sex life/Sexual orientation** | Any inference about sexuality | +| **Trade union** | Membership or affiliation | +| **Criminal** | Alleged or actual criminal activity | + + + **Exception:** Aggregate analysis without storing personal identifiers (no user IDs, usernames, or linkable data) may be allowed for research purposes, subject to applicable laws. + + +### Displaying X Content + +| Requirement | Details | +|-------------|---------| +| **Attribution** | Use proper X branding. Follow [Brand Guidelines](https://about.x.com/en/who-we-are/brand-toolkit). | +| **No alterations** | Only modify for display formatting (resizing). Don't edit content, remove timestamps, or strip metadata. | +| **No iframes** | Don't display X Content in iframes. Use official embeds or render directly. | +| **Respect removals** | Remove content within 24 hours if deleted on X. | --- @@ -362,11 +371,56 @@ Looking for inspiration? Here are categories of bots and apps that align with X' | Restriction | Limit | |-------------|-------| -| **Content redistribution** | Max 1.5M Post IDs per 30-day period | +| **Post ID redistribution** | Max 1.5M Post IDs per 30-day period to any single entity | +| **Hydrated content redistribution** | Max 50,000 hydrated Posts or Users per recipient per day | | **Rate limits** | Vary by endpoint and tier—[see API docs](/x-api/rate-limits) | | **AI/ML training** | Prohibited (except for Grok) | | **Non-API access** | Prohibited—scraping and browser automation = permanent ban | -| **Competitive benchmarking** | Prohibited—can't measure X performance for competitive analysis | +| **Competitive benchmarking** | Prohibited—can't measure X performance vs. competitors | +| **Multiple apps for same use case** | Prohibited—don't create duplicate apps to bypass limits | + +### Special Use Cases + +| Use Case | Requirement | +|----------|-------------| +| **Government use** | Requires Enterprise tier | +| **Commercial use** | Requires appropriate paid tier; free tier is non-commercial only | +| **Academic research** | May have different redistribution limits; contact X for details | +| **EU Digital Services Act research** | Specific non-commercial research provisions available | + +--- + +## Security & Compliance + +Your obligations as a developer: + + + + - Use **industry-standard security** practices to protect X data + - Never share your API credentials or tokens + - Store credentials securely (environment variables, secret managers—not in code) + - Implement proper authentication in your apps + + + + If you experience a security breach involving X data: + - **Notify X immediately** + - Take steps to mitigate the breach + - Cooperate with X's investigation + + + + - Treat any non-public information from X as confidential + - Don't disclose API rate limits, internal X data, or non-public features + - Don't use confidential info for competitive purposes + + + + - X may audit your compliance **up to once per year** + - You must provide reasonable access and documentation + - Keep records of how you use X data + + --- @@ -374,29 +428,38 @@ Looking for inspiration? Here are categories of bots and apps that align with X' + **For Automated Accounts:** - Enable "Automated" profile label - - Disclose bot operator in bio + - Disclose operator in bio - Wait for users to initiate interaction - Provide easy opt-out - - Disclose affiliate/sponsored relationships - - Respect rate limits - - Use only the official X API - Get approval for AI-generated replies - - Create non-duplicative regional accounts - - Mark sensitive content appropriately - - Stay within redistribution limits + + **For All Apps:** + - Use only the official X API + - Respect rate limits and redistribution limits + - Delete content within 24 hours when requested + - Get opt-in consent for off-X matching + - Use proper attribution when displaying X Content + - Secure your credentials and notify X of breaches + - Keep records of your X data usage - - Hide that it's a bot - - Impersonate humans + **For Automated Accounts:** + - Hide automated nature - Send unsolicited DMs, replies, or @mentions - Ignore "stop" requests - - Use misleading links or hidden promotions - - Try to circumvent limits or scrape - - Use browser automation or scraping - - Deploy AI replies without approval - Post identical content across accounts - - Post adult content without proper labels - - Redistribute >1.5M posts/30 days + - Use automated likes (banned entirely) + + **For All Apps:** + - Scrape or use browser automation + - Train AI/ML models on X data (except Grok) + - Derive sensitive user data (health, politics, religion, etc.) + - Match X data to off-platform IDs without consent + - Display X Content in iframes + - Redistribute more than limits allow + - Create multiple apps for the same use case + - Use X data for surveillance or user tracking From a48eb90b738af310aadc80d5fc2d336007371bda Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Thu, 12 Mar 2026 17:18:20 -0700 Subject: [PATCH 3/6] Update emojis to icons --- developer-guidelines.mdx | 96 ++++++++++++++++++++-------------------- 1 file changed, 48 insertions(+), 48 deletions(-) diff --git a/developer-guidelines.mdx b/developer-guidelines.mdx index 84d6eef9..1ddc34ce 100644 --- a/developer-guidelines.mdx +++ b/developer-guidelines.mdx @@ -65,70 +65,70 @@ Real-world examples to help you understand what's permitted. These cover automat | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot posts scheduled content (news, weather, quotes) | ✅ | Informational, no unsolicited mentions | - | Bot posts RSS feed updates automatically | ✅ | Helpful broadcasting | - | Bot posts earthquake/disaster alerts | ✅ | Public safety value | - | Bot posts sports scores or game updates | ✅ | Informational | - | Bot posts stock/crypto prices on schedule | ✅ | Informational, no manipulation | - | Bot posts identical content across multiple accounts | ❌ | Spam / platform manipulation | - | Bot posts to trending topics to gain visibility | ❌ | Trend manipulation | - | Multiple city-specific weather bots (e.g., @WeatherNYC, @WeatherLA) | ✅ | Allowed—non-duplicative, location-specific content | + | Bot posts scheduled content (news, weather, quotes) | | Informational, no unsolicited mentions | + | Bot posts RSS feed updates automatically | | Helpful broadcasting | + | Bot posts earthquake/disaster alerts | | Public safety value | + | Bot posts sports scores or game updates | | Informational | + | Bot posts stock/crypto prices on schedule | | Informational, no manipulation | + | Bot posts identical content across multiple accounts | | Spam / platform manipulation | + | Bot posts to trending topics to gain visibility | | Trend manipulation | + | Multiple city-specific weather bots (e.g., @WeatherNYC, @WeatherLA) | | Allowed—non-duplicative, location-specific content | | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot responds to @mentions asking for help | ✅ | User-initiated request | - | Bot replies to anyone mentioning a keyword | ❌ | Unsolicited interaction | - | Bot auto-replies to users who reply to your tweet | ✅* | User engaged first—limit 1 reply per interaction | - | AI-powered bot generates and posts replies | ⚠️ | Requires **prior approval** from X | - | Bot replies with "follow me for more!" to random users | ❌ | Spam, unsolicited | - | Thread unroller bot that responds when asked | ✅ | User-initiated utility | + | Bot responds to @mentions asking for help | | User-initiated request | + | Bot replies to anyone mentioning a keyword | | Unsolicited interaction | + | Bot auto-replies to users who reply to your tweet | * | User engaged first—limit 1 reply per interaction | + | AI-powered bot generates and posts replies | | Requires **prior approval** from X | + | Bot replies with "follow me for more!" to random users | | Spam, unsolicited | + | Thread unroller bot that responds when asked | | User-initiated utility | *Conditional—see [Gray Areas](#gray-areas-explained) section below. | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot responds to DMs with helpful info | ✅ | User-initiated | - | Bot sends affiliate links when user DMs first | ✅* | User-initiated—must disclose affiliate relationship | - | Bot auto-DMs new followers with welcome message | ❌ | Unsolicited, even to followers | - | Bot bulk-DMs users about a product launch | ❌ | Spam | - | Support bot asks "How can I help?" after user DMs | ✅ | User-initiated conversation | + | Bot responds to DMs with helpful info | | User-initiated | + | Bot sends affiliate links when user DMs first | * | User-initiated—must disclose affiliate relationship | + | Bot auto-DMs new followers with welcome message | | Unsolicited, even to followers | + | Bot bulk-DMs users about a product launch | | Spam | + | Support bot asks "How can I help?" after user DMs | | User-initiated conversation | *Conditional—see [Gray Areas](#gray-areas-explained) section below. | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot auto-likes posts containing a hashtag | ❌ | Automated likes banned | - | Bot auto-likes posts from a specific user | ❌ | Automated likes banned | - | Bot reposts content from a curated list | ✅* | OK for informational purposes, no bulk spam | - | Bot bulk-follows accounts to grow audience | ❌ | Manipulation | - | Bot follows back anyone who follows it | ❌ | Bulk/aggressive following | - | Bot adds users to lists in bulk | ❌ | Indiscriminate list manipulation | + | Bot auto-likes posts containing a hashtag | | Automated likes banned | + | Bot auto-likes posts from a specific user | | Automated likes banned | + | Bot reposts content from a curated list | * | OK for informational purposes, no bulk spam | + | Bot bulk-follows accounts to grow audience | | Manipulation | + | Bot follows back anyone who follows it | | Bulk/aggressive following | + | Bot adds users to lists in bulk | | Indiscriminate list manipulation | **Automated likes are banned with no exceptions.** This is one of the most common violations. | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot sends product recommendations when asked | ✅ | User-initiated | - | Bot replies to random posts with affiliate links | ❌ | Unsolicited spam | - | Giveaway bot that requires follows/retweets to enter | ⚠️ | Risky—can be seen as engagement manipulation | - | Bot selling likes/follows/retweets | ❌ | Strictly prohibited | - | Tip bot that sends crypto when user requests | ✅* | User-initiated—comply with financial regulations | + | Bot sends product recommendations when asked | | User-initiated | + | Bot replies to random posts with affiliate links | | Unsolicited spam | + | Giveaway bot that requires follows/retweets to enter | | Risky—can be seen as engagement manipulation | + | Bot selling likes/follows/retweets | | Strictly prohibited | + | Tip bot that sends crypto when user requests | * | User-initiated—comply with financial regulations | *Conditional—see [Gray Areas](#gray-areas-explained) section below. | Scenario | Allowed? | Why | |----------|:--------:|-----| - | App tracks brand mentions for analytics dashboard | ✅ | Valid use case | - | App scrapes X via browser automation (not API) | ❌ | **Permanent suspension**—API only | - | App stores X data to train AI/ML models | ❌ | Prohibited (except Grok) | - | App redistributes >1.5M posts in 30 days | ❌ | Exceeds redistribution limits | - | App benchmarks X performance vs competitors | ❌ | Prohibited competitive analysis | - | Academic research on public conversation trends | ✅ | Valid with proper data handling | + | App tracks brand mentions for analytics dashboard | | Valid use case | + | App scrapes X via browser automation (not API) | | **Permanent suspension**—API only | + | App stores X data to train AI/ML models | | Prohibited (except Grok) | + | App redistributes >1.5M posts in 30 days | | Exceeds redistribution limits | + | App benchmarks X performance vs competitors | | Prohibited competitive analysis | + | Academic research on public conversation trends | | Valid with proper data handling | **Non-API automation (scraping, browser automation) results in permanent suspension.** Always use the official X API. @@ -195,16 +195,16 @@ All automated accounts using the X API must meet these requirements: | Action | Allowed? | Rules | |--------|:--------:|-------| -| **Post tweets** | ✅ | No unsolicited @mentions. No identical cross-posting. | -| **Reply to users** | ⚠️ | Only if user engaged first. Max **1 reply per interaction**. | -| **Send DMs** | ⚠️ | Only after user DMs you first. Easy opt-out required. | -| **Like posts** | ❌ | **Automated likes are banned.** No exceptions. | -| **Repost** | ⚠️ | OK for informational/entertainment. No bulk spam. | -| **Quote tweet** | ⚠️ | Same rules as repost—no spam or manipulation. | -| **Follow/Unfollow** | ❌ | No bulk, aggressive, or automated following. | -| **Add to Lists** | ⚠️ | No bulk or indiscriminate additions. | -| **Bookmark** | ✅ | Fine for personal/automated use. | -| **Search/Read** | ✅ | Standard use within rate limits. | +| **Post tweets** | | No unsolicited @mentions. No identical cross-posting. | +| **Reply to users** | | Only if user engaged first. Max **1 reply per interaction**. | +| **Send DMs** | | Only after user DMs you first. Easy opt-out required. | +| **Like posts** | | **Automated likes are banned.** No exceptions. | +| **Repost** | | OK for informational/entertainment. No bulk spam. | +| **Quote tweet** | | Same rules as repost—no spam or manipulation. | +| **Follow/Unfollow** | | No bulk, aggressive, or automated following. | +| **Add to Lists** | | No bulk or indiscriminate additions. | +| **Bookmark** | | Fine for personal/automated use. | +| **Search/Read** | | Standard use within rate limits. | --- @@ -427,7 +427,7 @@ Your obligations as a developer: ## Summary: Do's and Don'ts - + **For Automated Accounts:** - Enable "Automated" profile label - Disclose operator in bio @@ -444,7 +444,7 @@ Your obligations as a developer: - Secure your credentials and notify X of breaches - Keep records of your X data usage - + **For Automated Accounts:** - Hide automated nature - Send unsolicited DMs, replies, or @mentions From 711e2be3792735cc9f1820b1ec3f26e9f93b8821 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Thu, 12 Mar 2026 11:24:20 -0700 Subject: [PATCH 4/6] Add profile.update.handle --- x-api/activity/introduction.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/x-api/activity/introduction.mdx b/x-api/activity/introduction.mdx index 1ae4c548..586ce7df 100644 --- a/x-api/activity/introduction.mdx +++ b/x-api/activity/introduction.mdx @@ -37,6 +37,7 @@ Profile events are triggered when a user makes changes to their profile informat | `profile.update.profile_picture` | Fired when a user updates their profile picture | `user_id` | | `profile.update.banner_picture` | Fired when a user updates their profile banner | `user_id` | | `profile.update.screenname` | Fired when a user updates their display name | `user_id` | +| `profile.update.handle` | Fired when a user updates their handle | `user_id` | | `profile.update.geo` | Fired when a user updates their profile location | `user_id` | | `profile.update.url` | Fired when a user updates their profile website URL | `user_id` | | `profile.update.verified_badge` | Fired when a user updates their verified badge | `user_id` | From 59ebd8e265cbc13ec6fbf34dbd9f0ed349763cf8 Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Thu, 12 Mar 2026 20:04:31 -0700 Subject: [PATCH 5/6] Update formatting --- developer-guidelines.mdx | 72 ++++++++++++++++++---------------------- 1 file changed, 33 insertions(+), 39 deletions(-) diff --git a/developer-guidelines.mdx b/developer-guidelines.mdx index 1ddc34ce..7c166cfc 100644 --- a/developer-guidelines.mdx +++ b/developer-guidelines.mdx @@ -59,66 +59,60 @@ Before building, ask yourself these questions. If you answer **"no"** to any of ## Common Scenarios: Allowed or Not? -Real-world examples to help you understand what's permitted. These cover automated accounts, integrations, and apps of all types. +Real-world examples to help you understand what's permitted. **These rules apply to all apps**—whether you're building a bot, mobile app, web integration, browser extension, analytics dashboard, or any other tool that uses the X API. | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot posts scheduled content (news, weather, quotes) | | Informational, no unsolicited mentions | - | Bot posts RSS feed updates automatically | | Helpful broadcasting | - | Bot posts earthquake/disaster alerts | | Public safety value | - | Bot posts sports scores or game updates | | Informational | - | Bot posts stock/crypto prices on schedule | | Informational, no manipulation | - | Bot posts identical content across multiple accounts | | Spam / platform manipulation | - | Bot posts to trending topics to gain visibility | | Trend manipulation | - | Multiple city-specific weather bots (e.g., @WeatherNYC, @WeatherLA) | | Allowed—non-duplicative, location-specific content | + | Automated account posts scheduled content (news, weather, quotes) | | Informational, no unsolicited mentions | + | App posts RSS feed updates on behalf of user | | Helpful broadcasting | + | Alert service posts earthquake/disaster notifications | | Public safety value | + | Sports app posts game updates to user's timeline | | Informational | + | App posts stock/crypto prices on schedule | | Informational, no manipulation | + | App posts identical content across multiple accounts | | Spam / platform manipulation | + | App posts to trending topics to gain visibility | | Trend manipulation | + | Multiple city-specific alert accounts (e.g., @WeatherNYC, @WeatherLA) | | Allowed—non-duplicative, location-specific content | | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot responds to @mentions asking for help | | User-initiated request | - | Bot replies to anyone mentioning a keyword | | Unsolicited interaction | - | Bot auto-replies to users who reply to your tweet | * | User engaged first—limit 1 reply per interaction | - | AI-powered bot generates and posts replies | | Requires **prior approval** from X | - | Bot replies with "follow me for more!" to random users | | Spam, unsolicited | - | Thread unroller bot that responds when asked | | User-initiated utility | - - *Conditional—see [Gray Areas](#gray-areas-explained) section below. + | App responds to @mentions asking for help | | User-initiated request | + | App auto-replies to anyone mentioning a keyword | | Unsolicited interaction | + | App auto-replies to users who reply to your post | | User engaged first—limit 1 reply. [Conditions apply](#gray-areas-explained) | + | AI-powered app generates and posts replies | | Requires **prior approval** from X | + | App replies with "follow me for more!" to random users | | Spam, unsolicited | + | Utility app that unrolls threads when mentioned | | User-initiated utility | | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot responds to DMs with helpful info | | User-initiated | - | Bot sends affiliate links when user DMs first | * | User-initiated—must disclose affiliate relationship | - | Bot auto-DMs new followers with welcome message | | Unsolicited, even to followers | - | Bot bulk-DMs users about a product launch | | Spam | - | Support bot asks "How can I help?" after user DMs | | User-initiated conversation | - - *Conditional—see [Gray Areas](#gray-areas-explained) section below. + | App responds to DMs with helpful info | | User-initiated | + | App sends affiliate links when user DMs first | | User-initiated—must disclose. [Conditions apply](#gray-areas-explained) | + | App auto-DMs new followers with welcome message | | Unsolicited, even to followers | + | App bulk-DMs users about a product launch | | Spam | + | Support integration asks "How can I help?" after user DMs | | User-initiated conversation | | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot auto-likes posts containing a hashtag | | Automated likes banned | - | Bot auto-likes posts from a specific user | | Automated likes banned | - | Bot reposts content from a curated list | * | OK for informational purposes, no bulk spam | - | Bot bulk-follows accounts to grow audience | | Manipulation | - | Bot follows back anyone who follows it | | Bulk/aggressive following | - | Bot adds users to lists in bulk | | Indiscriminate list manipulation | - - **Automated likes are banned with no exceptions.** This is one of the most common violations. + | App auto-likes posts containing a hashtag | | Automated likes banned | + | Mobile app has "auto-like" feature for selected users | | Automated likes banned | + | App reposts content from a curated list | | OK for informational purposes, no bulk spam. [Conditions apply](#gray-areas-explained) | + | Growth tool bulk-follows accounts to grow audience | | Manipulation | + | App follows back anyone who follows it | | Bulk/aggressive following | + | App adds users to lists in bulk | | Indiscriminate list manipulation | + + **Automated likes are banned with no exceptions.** This applies to all apps—bots, mobile apps, browser extensions, or any integration. | Scenario | Allowed? | Why | |----------|:--------:|-----| - | Bot sends product recommendations when asked | | User-initiated | - | Bot replies to random posts with affiliate links | | Unsolicited spam | - | Giveaway bot that requires follows/retweets to enter | | Risky—can be seen as engagement manipulation | - | Bot selling likes/follows/retweets | | Strictly prohibited | - | Tip bot that sends crypto when user requests | * | User-initiated—comply with financial regulations | - - *Conditional—see [Gray Areas](#gray-areas-explained) section below. + | App sends product recommendations when asked | | User-initiated | + | App replies to random posts with affiliate links | | Unsolicited spam | + | Giveaway app that requires follows/retweets to enter | | Risky—can be seen as engagement manipulation | + | Service selling likes/follows/retweets | | Strictly prohibited | + | Tip service that sends crypto when user requests | | User-initiated—comply with financial regulations. [Conditions apply](#gray-areas-explained) | | Scenario | Allowed? | Why | From 04b4141f149d2cf5d1b98d1d7325c8a10ec815bb Mon Sep 17 00:00:00 2001 From: Taylor Caldwell Date: Thu, 12 Mar 2026 20:31:46 -0700 Subject: [PATCH 6/6] Add developer guidelines and support --- developer-guidelines.mdx | 4 +- docs.json | 2 +- support.mdx | 138 +++++++++++++++++++++++++++++++++++++++ 3 files changed, 141 insertions(+), 3 deletions(-) create mode 100644 support.mdx diff --git a/developer-guidelines.mdx b/developer-guidelines.mdx index 7c166cfc..6f997782 100644 --- a/developer-guidelines.mdx +++ b/developer-guidelines.mdx @@ -226,7 +226,7 @@ Many developers have questions about edge cases. Here's guidance on common gray - **Requires prior approval from X** before deployment - Must still follow all rules (no unsolicited mentions, properly labeled) - - Contact [X Developer Support](https://docs.x.com/support) before launching + - Contact X via the [Policy Support form](https://help.x.com/forms/platform) before launching - Even with approval, cannot impersonate humans Deploying AI-generated replies without approval is a violation, even if the content itself is helpful. @@ -367,7 +367,7 @@ You must delete X Content from your systems when requested: |-------------|-------| | **Post ID redistribution** | Max 1.5M Post IDs per 30-day period to any single entity | | **Hydrated content redistribution** | Max 50,000 hydrated Posts or Users per recipient per day | -| **Rate limits** | Vary by endpoint and tier—[see API docs](/x-api/rate-limits) | +| **Rate limits** | Vary by endpoint and tier—[see API docs](/x-api/fundamentals/rate-limits) | | **AI/ML training** | Prohibited (except for Grok) | | **Non-API access** | Prohibited—scraping and browser automation = permanent ban | | **Competitive benchmarking** | Prohibited—can't measure X performance vs. competitors | diff --git a/docs.json b/docs.json index 7c654676..7f0d4637 100644 --- a/docs.json +++ b/docs.json @@ -1980,7 +1980,7 @@ "links": [ { "label": "Support", - "href": "https://developer.x.com/en/support" + "href": "/support" } ], "primary": { diff --git a/support.mdx b/support.mdx new file mode 100644 index 00000000..c9cb1eba --- /dev/null +++ b/support.mdx @@ -0,0 +1,138 @@ +--- +title: Developer Support +sidebarTitle: Support +description: Get help with the X API, connect with the community, and find the resources you need. +icon: life-ring +keywords: ["support", "help", "developer support", "contact", "community", "forums", "troubleshooting", "API help"] +--- + +Whether you're troubleshooting an issue, looking for guidance, or want to connect with other developers, we've got you covered. + +--- + +## Community & Help + + + + Ask questions, share your projects, and get help from the X developer community and team. This is the best place to get support for technical questions. + + + Check the current operational status of X API v2, Enterprise APIs, and the Developer Console. + + + +--- + +## Contact & Forms + + + + Interested in enterprise-level API access? Submit your interest and our team will reach out. + + + Get help with billing questions for Basic, Pro, and Enterprise API subscriptions. + + + Questions about policies, compliance, or need approval for specific use cases? Contact our policy team. + + + +--- + +## Documentation & Resources + + + + New to the X API? Start here to get your API keys and make your first request. + + + Complete reference for all X API v2 endpoints, parameters, and response formats. + + + Learn about OAuth 1.0a, OAuth 2.0, and how to authenticate your API requests. + + + Official Python and TypeScript SDKs to speed up your development. + + + Understand rate limits and how to handle them in your application. + + + Reference for API error codes and how to resolve common issues. + + + +--- + +## Policies & Guidelines + + + + Practical guide to what's allowed and what's not when building with the X API. + + + The binding legal terms for X API access. + + + Rules and expectations for building on X. + + + Activities that are prohibited or require special approval. + + + +--- + +## Troubleshooting Tips + + + + - Double-check your API keys and tokens are correct + - Ensure you're using the right authentication method for the endpoint (OAuth 1.0a vs OAuth 2.0) + - Verify your app has the required permissions (read, write, DM access) + - Check that your tokens haven't expired—regenerate if needed + + + + - Check the `x-rate-limit-*` headers in API responses to monitor your usage + - Implement exponential backoff when you receive 429 errors + - Cache responses where possible to reduce API calls + - Consider upgrading your access tier for higher limits + - See the [Rate Limits guide](/x-api/fundamentals/rate-limits) for detailed information + + + + - Review the [Developer Guidelines](/developer-guidelines) to understand what may have caused the suspension + - Check your email for any communication from X about the suspension + - Submit an appeal through the [Policy Support form](https://help.x.com/forms/platform) + - Common causes: automated likes, unsolicited DMs/mentions, scraping, rate limit abuse + + + + - Review the [pricing tiers](/x-api/getting-started/pricing) to find the right plan + - For enterprise needs, submit the [Enterprise API Interest form](/forms/enterprise-api-interest) + - For access upgrades, use the [Use Case Upgrade form](/forms/use-case/upgrade) + + + + - Browse the full [API Reference](/x-api/introduction) + - Check if the functionality exists in [v1.1 endpoints](/x-api/migrate/overview) that may not be in v2 yet + - Ask in the [Developer Forums](https://devcommunity.x.com) if you're unsure + + + +--- + +## Stay Updated + + + + Latest API updates, new features, and changes. + + + Follow for announcements and developer news. + + + History of past incidents and their resolutions. + +