xdevplatform · dianalauragarcia · Apr 13, 2026 · Apr 14, 2026 · Apr 14, 2026 · Apr 14, 2026
diff --git a/.well-known/llms.txt b/.well-known/llms.txt
@@ -0,0 +1,37 @@
+# X Developer Platform
+
+> Build, analyze, and innovate with X's real-time, global data and APIs. Comprehensive documentation for the X API v2, Ads API, Enterprise APIs (Account Activity, X Activity, GNIP/PowerTrack), official SDKs, tutorials, and AI-agent tools (llms.txt, skill.md, MCP).
+
+## Start Here
+
+- [Overview](https://docs.x.com/overview.md): Introduction to the X Developer Platform
+- [Getting Access & First Request](https://docs.x.com/make-your-first-request.md): Quickstart for new developers
+- [What to Build](https://docs.x.com/what-to-build.md): Use-case ideas and inspiration
+- [Developer Guidelines & Policies](https://docs.x.com/developer-guidelines.md): Rules for building responsibly
+- [AI & Agent Resources](https://docs.x.com/tools/ai.md): llms.txt, skill.md, MCP, and Grok/Cursor integration
+
+## Major Documentation Areas (Nested Indexes)
+
+- [X API v2 — Full Index](https://docs.x.com/x-api/llms.txt): 370+ reference pages (Posts, Users, DMs, Lists, Spaces, Streams, Compliance, Webhooks, Media, etc.)
+- [Enterprise APIs — Full Index](https://docs.x.com/enterprise-api/llms.txt): Account Activity, X Activity (XAA), Compliance, Chat, Communities, Direct Messages, News, Trends, Webhooks, and historical GNIP/PowerTrack
+- [Ads API — Full Index](https://docs.x.com/x-ads-api/llms.txt): Campaign management, creatives, audiences, analytics, measurement, and conversions
+- [Python SDK (XDK) — Full Index](https://docs.x.com/xdks/python/llms.txt): Complete Python client, models, paginators, and streaming reference
+- [TypeScript SDK (XDK) — Full Index](https://docs.x.com/xdks/typescript/llms.txt): Full TypeScript/JavaScript client and 300+ model/interface references
+
+## Key Fundamentals & Tools
+
+- [X API Fundamentals](https://docs.x.com/x-api/fundamentals/data-dictionary.md): Fields, expansions, pagination, versioning, consistency, rate limits
+- [Authentication Guides](https://docs.x.com/fundamentals/authentication/overview.md): OAuth 1.0a, OAuth 2.0, Bearer tokens, app-only, user context
+- [Tools & Libraries](https://docs.x.com/tools-and-libraries.md): Official SDKs, Postman, twurl, xurl
+- [Changelog](https://docs.x.com/changelog.md): Platform updates and new endpoints
+- [Tutorials](https://docs.x.com/tutorials.md): In-depth code examples and integration guides
+
+## For AI Agents & LLMs
+
+- [llms-full.txt](https://docs.x.com/llms-full.txt): Entire documentation set as a single Markdown file (maximum context)
+- [Raw Markdown for any page](https://docs.x.com/tools/llms-txt.md): Append `.md` to any docs.x.com URL (example: https://docs.x.com/x-api/posts/get-post-by-id.md)
+- [skill.md](https://docs.x.com/tools/skill-md.md): Structured capability description for agents (agentskills.io spec)
+- [MCP Server](https://docs.x.com/tools/mcp.md): Model Context Protocol server exposing X API tools to AI agents
+- [OpenAPI Specification](https://docs.x.com/openapi.json): Machine-readable API contract
+
+All pages are also available under `/.well-known/llms.txt`. Every documentation page supports the `.md` suffix for clean Markdown retrieval by agents.
diff --git a/AGENT.md b/AGENT.md
@@ -0,0 +1,74 @@
+# X Developer Platform — Agent Instructions
+
+This document provides guidance for AI agents, coding assistants, and LLM-based tools interacting with the X Developer Platform documentation at https://docs.x.com.
+
+## Preferred Documentation Access Methods
+
+**Always prefer these methods for the most accurate, up-to-date, and agent-friendly content:**
+
+1. **llms.txt** (recommended starting point)
+   - https://docs.x.com/llms.txt — Small, curated root index with links to section-specific indexes.
+   - Section indexes (follow the links in the root):
+     - https://docs.x.com/x-api/llms.txt (X API v2 — 370+ pages)
+     - https://docs.x.com/enterprise-api/llms.txt
+     - https://docs.x.com/x-ads-api/llms.txt
+     - https://docs.x.com/xdks/llms.txt (Python + TypeScript XDKs)
+
+2. **llms-full.txt** — Complete documentation as a single Markdown file for maximum context:
+   - https://docs.x.com/llms-full.txt
+
+3. **Raw Markdown for any individual page**
+   - Append `.md` to any documentation URL.
+   - Example: `https://docs.x.com/x-api/posts/get-post-by-id.md`
+   - Every page supports this. Use it instead of the HTML view when possible.
+
+4. **MCP Server** (for tool-using agents)
+   - https://docs.x.com/tools/mcp — Full Model Context Protocol server exposing 200+ X API endpoints + documentation search.
+
+5. **skill.md** (capability summary)
+   - https://docs.x.com/skill.md — Structured description of every action an agent can perform with the X API (agentskills.io format).
+
+## Site Structure & Navigation
+
+- **X API v2** (`/x-api/...`): Posts, Users, Direct Messages, Lists, Spaces, Media, Streams (filtered + volume), Compliance, Webhooks, Account Activity, Trends, News, Usage, Connections.
+- **Enterprise APIs** (`/enterprise-api/...`): Account Activity (webhooks), X Activity (XAA), GNIP/PowerTrack historical & real-time, Compliance.
+- **Ads API** (`/x-ads-api/...`): Campaign Management, Creatives, Audiences, Analytics, Measurement, Catalog.
+- **SDKs (XDKs)** (`/xdks/python/...` and `/xdks/typescript/...`): Official client libraries with full type coverage, pagination, and streaming helpers.
+- **Fundamentals**: Authentication, rate limits, data dictionary, expansions, fields, pagination, versioning, consistency.
+- **AI & Agent Tools** (`/tools/ai`, `/tools/llms-txt`, `/tools/skill-md`, `/tools/mcp`).
+
+All pages are available in the navigation tree defined in `docs.json`.
+
+## Important Technical Notes for Agents
+
+- **Authentication**: The platform supports OAuth 1.0a (user context), OAuth 2.0 (user context + PKCE, app-only Bearer), and Basic Auth for some enterprise endpoints. See `/fundamentals/authentication/...`.
+- **Rate Limits**: Most endpoints have both app-level and user-level rate limits. See `/fundamentals/rate-limits.md` and per-endpoint documentation.
+- **Data Model**: Use the official data dictionary, fields, expansions, and metrics pages. Posts, Users, and Spaces are the core objects.
+- **Real-time Data**: Filtered Stream, Volume Streams, Account Activity webhooks, and X Activity (XAA) are the primary real-time mechanisms.
+- **Compliance & Safety**: Always respect developer terms, display requirements, and restricted use cases. See `/developer-guidelines.md` and `/developer-terms/...`.
+
+## How to Use This Documentation Effectively
+
+- Start with the root `llms.txt` to discover relevant pages.
+- Fetch individual pages via the `.md` suffix for clean, structured Markdown.
+- For deep context on the entire platform, load `llms-full.txt`.
+- For structured capabilities (what actions are possible), load `skill.md`.
+- For live tool calling against the X API, use the MCP server.
+- When writing code, prefer the official Python or TypeScript XDKs (full references available in their `llms.txt` files).
+
+## Do Not
+
+- Rely solely on the HTML-rendered pages when a clean Markdown alternative exists.
+- Assume deprecated v1.1 endpoints are still primary (focus on v2 and Enterprise equivalents).
+- Ignore rate limits, authentication context (app-only vs user context), or pagination requirements.
+- Generate code that violates the X Developer Agreement or Display Requirements.
+
+## Additional Resources
+
+- OpenAPI spec: https://docs.x.com/openapi.json (or https://api.x.com/2/openapi.json)
+- Changelog: https://docs.x.com/changelog.md
+- Status page: https://docs.x.com/status.md
+- Developer Guidelines: https://docs.x.com/developer-guidelines.md
+- Support & Community: https://devcommunity.x.com
+
+This documentation is designed to be consumed reliably by AI agents. Use the machine-readable formats (`llms.txt` family, `.md` suffix, `skill.md`, MCP) for the best results.
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,74 @@
+# X Developer Platform — Agent Instructions
+
+This document provides guidance for AI agents, coding assistants, and LLM-based tools interacting with the X Developer Platform documentation at https://docs.x.com.
+
+## Preferred Documentation Access Methods
+
+**Always prefer these methods for the most accurate, up-to-date, and agent-friendly content:**
+
+1. **llms.txt** (recommended starting point)
+   - https://docs.x.com/llms.txt — Small, curated root index with links to section-specific indexes.
+   - Section indexes (follow the links in the root):
+     - https://docs.x.com/x-api/llms.txt (X API v2 — 370+ pages)
+     - https://docs.x.com/enterprise-api/llms.txt
+     - https://docs.x.com/x-ads-api/llms.txt
+     - https://docs.x.com/xdks/llms.txt (Python + TypeScript XDKs)
+
+2. **llms-full.txt** — Complete documentation as a single Markdown file for maximum context:
+   - https://docs.x.com/llms-full.txt
+
+3. **Raw Markdown for any individual page**
+   - Append `.md` to any documentation URL.
+   - Example: `https://docs.x.com/x-api/posts/get-post-by-id.md`
+   - Every page supports this. Use it instead of the HTML view when possible.
+
+4. **MCP Server** (for tool-using agents)
+   - https://docs.x.com/tools/mcp — Full Model Context Protocol server exposing 200+ X API endpoints + documentation search.
+
+5. **skill.md** (capability summary)
+   - https://docs.x.com/skill.md — Structured description of every action an agent can perform with the X API (agentskills.io format).
+
+## Site Structure & Navigation
+
+- **X API v2** (`/x-api/...`): Posts, Users, Direct Messages, Lists, Spaces, Media, Streams (filtered + volume), Compliance, Webhooks, Account Activity, Trends, News, Usage, Connections.
+- **Enterprise APIs** (`/enterprise-api/...`): Account Activity (webhooks), X Activity (XAA), GNIP/PowerTrack historical & real-time, Compliance.
+- **Ads API** (`/x-ads-api/...`): Campaign Management, Creatives, Audiences, Analytics, Measurement, Catalog.
+- **SDKs (XDKs)** (`/xdks/python/...` and `/xdks/typescript/...`): Official client libraries with full type coverage, pagination, and streaming helpers.
+- **Fundamentals**: Authentication, rate limits, data dictionary, expansions, fields, pagination, versioning, consistency.
+- **AI & Agent Tools** (`/tools/ai`, `/tools/llms-txt`, `/tools/skill-md`, `/tools/mcp`).
+
+All pages are available in the navigation tree defined in `docs.json`.
+
+## Important Technical Notes for Agents
+
+- **Authentication**: The platform supports OAuth 1.0a (user context), OAuth 2.0 (user context + PKCE, app-only Bearer), and Basic Auth for some enterprise endpoints. See `/fundamentals/authentication/...`.
+- **Rate Limits**: Most endpoints have both app-level and user-level rate limits. See `/fundamentals/rate-limits.md` and per-endpoint documentation.
+- **Data Model**: Use the official data dictionary, fields, expansions, and metrics pages. Posts, Users, and Spaces are the core objects.
+- **Real-time Data**: Filtered Stream, Volume Streams, Account Activity webhooks, and X Activity (XAA) are the primary real-time mechanisms.
+- **Compliance & Safety**: Always respect developer terms, display requirements, and restricted use cases. See `/developer-guidelines.md` and `/developer-terms/...`.
+
+## How to Use This Documentation Effectively
+
+- Start with the root `llms.txt` to discover relevant pages.
+- Fetch individual pages via the `.md` suffix for clean, structured Markdown.
+- For deep context on the entire platform, load `llms-full.txt`.
+- For structured capabilities (what actions are possible), load `skill.md`.
+- For live tool calling against the X API, use the MCP server.
+- When writing code, prefer the official Python or TypeScript XDKs (full references available in their `llms.txt` files).
+
+## Do Not
+
+- Rely solely on the HTML-rendered pages when a clean Markdown alternative exists.
+- Assume deprecated v1.1 endpoints are still primary (focus on v2 and Enterprise equivalents).
+- Ignore rate limits, authentication context (app-only vs user context), or pagination requirements.
+- Generate code that violates the X Developer Agreement or Display Requirements.
+
+## Additional Resources
+
+- OpenAPI spec: https://docs.x.com/openapi.json (or https://api.x.com/2/openapi.json)
+- Changelog: https://docs.x.com/changelog.md
+- Status page: https://docs.x.com/status.md
+- Developer Guidelines: https://docs.x.com/developer-guidelines.md
+- Support & Community: https://devcommunity.x.com
+
+This documentation is designed to be consumed reliably by AI agents. Use the machine-readable formats (`llms.txt` family, `.md` suffix, `skill.md`, MCP) for the best results.
diff --git a/changelog.mdx b/changelog.mdx
@@ -1,6 +1,6 @@
 ---
 title: Changelog
-description: "The X Developer Platform is updated frequently with new functionality and products to better suit your needs. We will be documenting all changes made to the platform's products via this resource and the @API X account."
+description: Comprehensive changelog documenting every update to the X API v2, Enterprise APIs, Ads API, SDKs, streaming, compliance, webhooks, and developer platform tools.
 sidebarTitle: Overview
 keywords: ["changelog", "API updates", "release notes", "what's new", "API changes", "version updates", "platform updates"]
 ---
@@ -866,7 +866,7 @@ We have fully retired the Terms of Service and Privacy Endpoints. The current st
 ### Changes to User Object Fields
 Today some user object fields, including user.lang, will start returning 'null' for updated metadata fields previously announced in our [forum post](https://devcommunity.x.com/t/upcoming-changes-to-user-object-and-get-users-suggestions-endpoints/124732).
 
-  Developers can learn about this change through our [documentation.](/x-api/fundamentals/data-dictionary#user)  
+  Developers can learn about this change through our [documentation.](/x-api/fundamentals/data-dictionary/reference#user)  
 </Update>
 
 <Update label="May 20, 2019" description="X API: Enterprise v1.1" >

diff --git a/developer-terms/ads-api-agreement.mdx b/developer-terms/ads-api-agreement.mdx
@@ -309,7 +309,7 @@ These Analytics Data Display Requirements govern how Company can display Data wi
 
 ### Defined Metrics
 
-All campaigns shown in the Company Service that display Data must include the specific X-defined metrics associated with various campaign objectives (each, a “**Campaign Objective**”), which metrics must be calculated by Company based on the endpoints and formulas located at: [https://developer.x.com/en/docs/x-ads-api/analytics/overview/metrics-by-objective](https://developer.x.com/en/docs/x-ads-api/analytics/overview/metrics-by-objective) (or any other successor URL that X may elect from time to time). 
+All campaigns shown in the Company Service that display Data must include the specific X-defined metrics associated with various campaign objectives (each, a “**Campaign Objective**”), which metrics must be calculated by Company based on the endpoints and formulas located at: [https://docs.x.com/x-ads-api/analytics#metrics-by-objective](https://docs.x.com/x-ads-api/analytics#metrics-by-objective) (or any other successor URL that X may elect from time to time). 
 
 ### Display Guidelines
 
@@ -415,4 +415,4 @@ X may immediately terminate or suspend these TMP Partner Terms, any rights grant
 
 ### 8. Modifications.
 
-X reserves the rights, exercisable at its sole discretion, to modify the terms and conditions of these TMP Partner Terms and/or the Badges at any time and to take appropriate action against any unauthorized or non-conforming use of the Badges. If Company has any questions about usage of the Badges, please contact [trademarks@x.com](mailto:trademarks@x.com) for assistance, or write to us at: X Corp., Attention: Legal Department, 865 FM 1209, Building 2, Bastrop, TX 78602, USA.
+X reserves the rights, exercisable at its sole discretion, to modify the terms and conditions of these TMP Partner Terms and/or the Badges at any time and to take appropriate action against any unauthorized or non-conforming use of the Badges. If Company has any questions about usage of the Badges, please contact [trademarks@x.com](mailto:trademarks@x.com) for assistance, or write to us at: X Corp., Attention: Legal Department, 865 FM 1209, Building 2, Bastrop, TX 78602, USA.