> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To act on Guild from an MCP client, connect to https://api.guild.ai/mcp (OAuth) or run `guild mcp` locally. Setup: https://docs.guild.ai/api-reference/mcp.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# Post, search, and stream X from Guild agents

> Let Guild agents post tweets, send DMs, search content, manage lists, stream live tweet data, and handle compliance on X using a bearer token.

Integrations · X

Guild agents post tweets, send direct messages, search content, manage lists and follows, and stream live tweet data on X. Credentials are stored server-side and injected by Guild's credential proxy, so agent code never sees the bearer token. Credential policies let you restrict which operations each agent can call before any request reaches X.

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use X.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect X to your first agent.

## What the X integration exposes

The integration gives agents tools that cover posts, direct messages, users, follows, likes, bookmarks, lists, Spaces, streaming, and compliance on the X v2 API. Tools are prefixed with `x_openapi_` and imported from `XOpenapiTools`. Use `pick()` to give each agent only the tools it needs.

## How it works

**1. Open credentials in Guild**

Go to Access & setup > Credentials in your Guild account or organization. Click Connect, search for x-openapi, and select it.

**2. Paste your bearer token**

Guild prompts for an API key. Paste your X bearer token; Guild stores it and sends it in the Authorization header on every agent request.

**3. Import tools into your agent**

Import `XOpenapiTools` from `@guildai-services/guildai~x-openapi` and spread it into your agent's `tools` object. Use `pick()` to include only the tools your agent needs.

## Why X access needs governing

An unscoped X bearer token can post tweets, send direct messages, block users, and stream live public data. Credential policies let you write ALLOW and DENY rules that Guild's credential proxy enforces before any request reaches X. You can allow only read operations by restricting to `GET` methods, block destructive operations such as `x_openapi_delete_tweet_by_id`, or scope rules to specific agents or workspaces on the same credential.

Guild stores the bearer token server-side and injects it after the policy check passes. Agents never see the credential. You can scope a credential to a single agent, a single workspace, or a single member, so a social-posting agent and a compliance-monitoring agent never share the same token or the same access rules. See [Credentials](https://docs.guild.ai/platform/credentials.md) and [Credential policies](https://docs.guild.ai/platform/credential-policies.md) for setup details.

## About the X integration

Agents can read and write on X using the v2 API, including creating tweets, sending direct messages, searching tweets and Spaces, and managing lists and user relationships. They can also stream live tweet data and retrieve compliance information. Authentication requires a bearer token. The integration is `guildai~x-openapi`.

## Authentication

* **Type:** API key
* **Header:** Guild sends the key as a bearer token in the `Authorization` header

### Setup

**1. Connect X**

In Guild, go to **Access & setup > Credentials**, click **Connect**, select **x-openapi**, and paste the key into **API Key**.

See [Credentials](https://docs.guild.ai/platform/credentials.md) for workspace, member, and agent-scoped credentials.

## Usage

```typescript theme={null}
import { XOpenapiTools } from "@guildai-services/guildai~x-openapi"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  systemPrompt: "You work with X.",
  tools: { ...XOpenapiTools },
})
```

### Selecting specific tools

Tools are named with the `x_openapi_` prefix. Use [`pick()`](https://docs.guild.ai/sdk/tools#selecting-specific-tools) to include only what your agent needs.

## Tools

Tools in the latest published version of `guildai~x-openapi`:

> [accordion] All 80 tools
>
> | Tool | What it does |
> | - | - |
> | `x_openapi_add_or_delete_rules` | Add or delete rules from a User's active rule set. |
> | `x_openapi_create_batch_compliance_job` | Creates a compliance for the given job type |
> | `x_openapi_create_tweet` | Causes the User to create a Tweet under the authorized account. |
> | `x_openapi_delete_tweet_by_id` | Delete specified Tweet (in the path) by ID. |
> | `x_openapi_dm_conversation_by_id_event_id_create` | Creates a new message for a DM Conversation specified by DM Conversation ID |
> | `x_openapi_dm_conversation_id_create` | Creates a new DM Conversation. |
> | `x_openapi_dm_conversation_with_user_event_id_create` | Creates a new message for a DM Conversation with a participant user by ID |
> | `x_openapi_find_my_user` | This endpoint returns information about the requesting User. |
> | `x_openapi_find_space_by_id` | Returns a variety of information about the Space specified by the requested ID |
> | `x_openapi_find_spaces_by_creator_ids` | Returns a variety of information about the Spaces created by the provided User IDs |
> | `x_openapi_find_spaces_by_ids` | Returns a variety of information about the Spaces specified by the requested IDs |
> | `x_openapi_find_tweet_by_id` | Returns a variety of information about the Tweet specified by the requested ID. |
> | `x_openapi_find_tweets_by_id` | Returns a variety of information about the Tweet specified by the requested ID. |
> | `x_openapi_find_tweets_that_quote_a_tweet` | Returns a variety of information about each Tweet that quotes the Tweet specified by the requested ID. |
> | `x_openapi_find_user_by_id` | This endpoint returns information about a User. |
> | `x_openapi_find_user_by_username` | This endpoint returns information about a User. |
> | `x_openapi_find_users_by_id` | This endpoint returns information about Users. |
> | `x_openapi_find_users_by_username` | This endpoint returns information about Users. |
> | `x_openapi_get_batch_compliance_job` | Returns a single Compliance Job by ID |
> | `x_openapi_get_dm_conversations_id_dm_events` | Returns DM Events for a DM Conversation |
> | `x_openapi_get_dm_conversations_with_participant_id_dm_events` | Returns DM Events for a DM Conversation |
> | `x_openapi_get_dm_events` | Returns recent DM Events across DM conversations |
> | `x_openapi_get_open_api_spec` | Full OpenAPI Specification in JSON format. (See [https://github.com/OAI/OpenAPI-Specification/blob/master/README.md](https://github.com/OAI/OpenAPI-Specification/blob/master/README.md)) |
> | `x_openapi_get_rules` | Returns rules from a User's active rule set. |
> | `x_openapi_get_tweets_compliance_stream` | Streams 100% of compliance data for Tweets |
> | `x_openapi_get_tweets_firehose_stream` | Streams 100% of public Tweets. |
> | `x_openapi_get_tweets_label_stream` | Streams 100% of labeling events applied to Tweets |
> | `x_openapi_get_tweets_sample10_stream` | Streams a deterministic 10% of public Tweets. |
> | `x_openapi_get_user_list_memberships` | Get a User's List Memberships. |
> | `x_openapi_get_users_compliance_stream` | Streams 100% of compliance data for Users |
> | `x_openapi_get_users_id_bookmarks` | Returns Tweet objects that have been bookmarked by the requesting User |
> | `x_openapi_hide_reply_by_id` | Hides or unhides a reply to an owned conversation. |
> | `x_openapi_list_add_member` | Causes a User to become a member of a List. |
> | `x_openapi_list_batch_compliance_jobs` | Returns recent Compliance Jobs for a given job type and optional job status |
> | `x_openapi_list_get_followers` | Returns a list of Users that follow a List by the provided List ID |
> | `x_openapi_list_get_members` | Returns a list of Users that are members of a List by the provided List ID. |
> | `x_openapi_list_id_create` | Creates a new List. |
> | `x_openapi_list_id_delete` | Delete a List that you own. |
> | `x_openapi_list_id_get` | Returns a List. |
> | `x_openapi_list_id_update` | Update a List that you own. |
> | `x_openapi_list_remove_member` | Causes a User to be removed from the members of a List. |
> | `x_openapi_lists_id_tweets` | Returns a list of Tweets associated with the provided List ID. |
> | `x_openapi_list_user_follow` | Causes a User to follow a List. |
> | `x_openapi_list_user_owned_lists` | Get a User's Owned Lists. |
> | `x_openapi_list_user_pin` | Causes a User to pin a List. |
> | `x_openapi_list_user_pinned_lists` | Get a User's Pinned Lists. |
> | `x_openapi_list_user_unfollow` | Causes a User to unfollow a List. |
> | `x_openapi_list_user_unpin` | Causes a User to remove a pinned List. |
> | `x_openapi_post_users_id_bookmarks` | Adds a Tweet (ID in the body) to the requesting User's (in the path) bookmarks |
> | `x_openapi_sample_stream` | Streams a deterministic 1% of public Tweets. |
> | `x_openapi_search_spaces` | Returns Spaces that match the provided query. |
> | `x_openapi_search_stream` | Streams Tweets matching the stream's active rule set. |
> | `x_openapi_space_buyers` | Retrieves the list of Users who purchased a ticket to the given space |
> | `x_openapi_space_tweets` | Retrieves Tweets shared in the specified Space. |
> | `x_openapi_tweet_counts_full_archive_search` | Returns Tweet Counts that match a search query. |
> | `x_openapi_tweet_counts_recent_search` | Returns Tweet Counts from the last 7 days that match a search query. |
> | `x_openapi_tweets_fullarchive_search` | Returns Tweets that match a search query. |
> | `x_openapi_tweets_id_liking_users` | Returns a list of Users that have liked the provided Tweet ID |
> | `x_openapi_tweets_id_retweeting_users` | Returns a list of Users that have retweeted the provided Tweet ID |
> | `x_openapi_tweets_recent_search` | Returns Tweets from the last 7 days that match a search query. |
> | `x_openapi_user_followed_lists` | Returns a User's followed Lists. |
> | `x_openapi_users_id_block` | Causes the User (in the path) to block the target User. |
> | `x_openapi_users_id_blocking` | Returns a list of Users that are blocked by the provided User ID |
> | `x_openapi_users_id_bookmarks_delete` | Removes a Tweet from the requesting User's bookmarked Tweets. |
> | `x_openapi_users_id_follow` | Causes the User(in the path) to follow, or “request to follow” for protected Users, the target User. |
> | `x_openapi_users_id_followers` | Returns a list of Users who are followers of the specified User ID. |
> | `x_openapi_users_id_following` | Returns a list of Users that are being followed by the provided User ID |
> | `x_openapi_users_id_like` | Causes the User (in the path) to like the specified Tweet. |
> | `x_openapi_users_id_liked_tweets` | Returns a list of Tweets liked by the provided User ID |
> | `x_openapi_users_id_mentions` | Returns Tweet objects that mention username associated to the provided User ID |
> | `x_openapi_users_id_mute` | Causes the User (in the path) to mute the target User. |
> | `x_openapi_users_id_muting` | Returns a list of Users that are muted by the provided User ID |
> | `x_openapi_users_id_retweets` | Causes the User (in the path) to retweet the specified Tweet. |
> | `x_openapi_users_id_timeline` | Returns Tweet objects that appears in the provided User ID's home timeline |
> | `x_openapi_users_id_tweets` | Returns a list of Tweets authored by the provided User ID |
> | `x_openapi_users_id_unblock` | Causes the source User to unblock the target User. |
> | `x_openapi_users_id_unfollow` | Causes the source User to unfollow the target User. |
> | `x_openapi_users_id_unlike` | Causes the User (in the path) to unlike the specified Tweet. |
> | `x_openapi_users_id_unmute` | Causes the source User to unmute the target User. |
> | `x_openapi_users_id_unretweets` | Causes the User (in the path) to unretweet the specified Tweet. |

## Frequently asked questions

> [accordion] Can an agent stream live tweets in real time?
>
> Yes. The `x_openapi_get_tweets_firehose_stream` tool streams 100% of public tweets, `x_openapi_search_stream` streams tweets matching the agent's active rule set, and `x_openapi_get_tweets_sample10_stream` streams a deterministic 10% sample.

> [accordion] Does Guild support webhook events from X?
>
> No. The catalog entry for `guildai~x-openapi` lists no webhook events, so the integration does not receive push notifications from X.

> [accordion] How do I stop one agent from deleting tweets while another can?
>
> Write a DENY rule on `x_openapi_delete_tweet_by_id` scoped to the agent that should not delete, and an ALLOW rule scoped to the one that should. Guild's credential proxy enforces these rules before any request leaves Guild. See [Credential policies](https://docs.guild.ai/platform/credential-policies.md).

> [accordion] Can I use different X accounts in different workspaces?
>
> Yes. Connect one bearer token as the account default and connect a second token scoped to a specific workspace. Guild selects the most specific credential first, so the workspace credential takes precedence for agents in that workspace. See [Credentials](https://docs.guild.ai/platform/credentials.md) for the full resolution order.

## Put a governed agent on X this week

> [card] [Book a demo](https://guild-ai.cal.com/gtm/meeting-with-guild.ai)
>
> See how teams govern agents that use X.

> [card] [Talk to sales](https://guild.ai/talk-to-sales)
>
> Get access to Guild, then connect X to your first agent.

## Related

**Also runs on Guild:** [Discord](https://docs.guild.ai/integrations/discord.md) · [Email](https://docs.guild.ai/integrations/email.md) · [Gmail](https://docs.guild.ai/integrations/gmail.md) · [SendGrid](https://docs.guild.ai/integrations/sendgrid.md)

**Read:** Docs: [Credential policies](https://docs.guild.ai/platform/credential-policies.md) · [Credentials](https://docs.guild.ai/platform/credentials.md) · [Tools in agents](https://docs.guild.ai/sdk/tools.md)
