diff --git a/developer-guidelines.mdx b/developer-guidelines.mdx
new file mode 100644
index 00000000..6f997782
--- /dev/null
+++ b/developer-guidelines.mdx
@@ -0,0 +1,459 @@
+---
+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 App Allowed?
+
+Before building, ask yourself these questions. If you answer **"no"** to any of them, your app likely violates X's policies.
+
+
+
+ For interactions, did the user **explicitly request** it?
+
+
+ Is your app's purpose and behavior **clear to users**? (Automated accounts must be labeled.)
+
+
+ Can users **easily opt out** of any ongoing 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 respecting usage policies?
+
+
+
+
+ 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. **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 |
+ |----------|:--------:|-----|
+ | 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 |
+ |----------|:--------:|-----|
+ | 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 |
+ |----------|:--------:|-----|
+ | 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 |
+ |----------|:--------:|-----|
+ | 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 |
+ |----------|:--------:|-----|
+ | 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 |
+ |----------|:--------:|-----|
+ | 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
+
+
+ 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:
+
+
+
+ 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.
+
+
+
+### Automated Actions: What's Allowed?
+
+| 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 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.
+
+
+
+ **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.
+
+
+
+---
+
+## Data Handling & Display Requirements
+
+
+ These requirements are legally binding under the Developer Agreement. Non-compliance can result in termination and legal action.
+
+
+### Content Deletion
+
+You must delete X Content from your systems when requested:
+
+| 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) |
+
+
+ Use [Compliance Firehose](https://docs.x.com/x-api/compliance/streams) to receive real-time deletion events and stay compliant automatically.
+
+
+### 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. |
+
+---
+
+## Technical Restrictions
+
+
+ These limits apply to all developers. Exceeding them can result in rate limiting or suspension.
+
+
+| Restriction | Limit |
+|-------------|-------|
+| **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/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 |
+| **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
+
+
+
+---
+
+## Summary: Do's and Don'ts
+
+
+
+ **For Automated Accounts:**
+ - Enable "Automated" profile label
+ - Disclose operator in bio
+ - Wait for users to initiate interaction
+ - Provide easy opt-out
+ - Get approval for AI-generated replies
+
+ **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
+
+
+ **For Automated Accounts:**
+ - Hide automated nature
+ - Send unsolicited DMs, replies, or @mentions
+ - Ignore "stop" requests
+ - Post identical content across accounts
+ - 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
+
+
diff --git a/docs.json b/docs.json
index ec058344..7f0d4637 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"
]
}
]
@@ -1985,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.
+
+
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` |