x-openapi-skill

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

X API Skill

X API 技能

Use this skill to run X API v2 operations through

uxc

+ OpenAPI.

Reuse the

uxc

skill for shared execution, auth, and error-handling guidance.

使用本技能可通过

uxc

+ OpenAPI执行X API v2操作。

复用

uxc

技能以获取通用的执行、认证和错误处理指南。

Prerequisites

前置条件

```
uxc
```
is installed and available in
```
PATH
```
.
Network access to
```
https://api.x.com
```
.
Access to the official OpenAPI schema URL:
- ```
https://api.x.com/2/openapi.json
```
An X developer app with OAuth2 enabled.

已安装
```
uxc
```
且其路径已添加至
```
PATH
```
环境变量。
可访问
```
https://api.x.com
```
网络。
可访问官方OpenAPI Schema地址：
- ```
https://api.x.com/2/openapi.json
```
已启用OAuth2的X开发者应用。

Authentication

认证方式

Preferred Path: OAuth2 Authorization Code + PKCE (User Context)

推荐方式：OAuth2授权码+PKCE（用户上下文）

This path is required for user-context operations such as bookmarks, home timeline, posting, replying, and DM actions.

Start OAuth2 login:

bash

uxc auth oauth start x-api-user \
  --endpoint https://api.x.com/2 \
  --client-id M3VseG9xOXZXZVREZnNqWk9jN1I6MTpjaQ \
  --redirect-uri http://127.0.0.1:11111/callback \
  --scope users.read \
  --scope tweet.read \
  --scope tweet.write \
  --scope tweet.moderate.write \
  --scope media.write \
  --scope like.read \
  --scope like.write \
  --scope follows.read \
  --scope follows.write \
  --scope list.read \
  --scope list.write \
  --scope timeline.read \
  --scope space.read \
  --scope mute.read \
  --scope mute.write \
  --scope block.read \
  --scope block.write \
  --scope bookmark.read \
  --scope bookmark.write \
  --scope dm.read \
  --scope dm.write \
  --authorization-endpoint https://x.com/i/oauth2/authorize \
  --token-endpoint https://api.x.com/2/oauth2/token

This default example intentionally includes the full OAuth2 user scope set exposed by the current X OpenAPI surface, excluding

offline.access

to avoid refresh-token compatibility failures observed on some X app configurations. Add

--scope offline.access

only when you explicitly need long-lived refresh behavior and have verified token refresh works for your app.

Open the returned authorization URL in browser and finish consent.
Complete login with the callback URL:

bash

uxc auth oauth complete x-api-user \
  --session-id <session_id> \
  --authorization-response '<callback_url>'

Bind credential to X API:

bash

uxc auth binding add \
  --id x-api-user \
  --host api.x.com \
  --path-prefix /2 \
  --scheme https \
  --credential x-api-user \
  --priority 100

Verify binding:

bash

uxc auth binding match https://api.x.com/2

此方式适用于需要用户上下文的操作，例如书签、首页时间线、发布、回复及私信操作。

启动OAuth2登录：

bash

uxc auth oauth start x-api-user \
  --endpoint https://api.x.com/2 \
  --client-id M3VseG9xOXZXZVREZnNqWk9jN1I6MTpjaQ \
  --redirect-uri http://127.0.0.1:11111/callback \
  --scope users.read \
  --scope tweet.read \
  --scope tweet.write \
  --scope tweet.moderate.write \
  --scope media.write \
  --scope like.read \
  --scope like.write \
  --scope follows.read \
  --scope follows.write \
  --scope list.read \
  --scope list.write \
  --scope timeline.read \
  --scope space.read \
  --scope mute.read \
  --scope mute.write \
  --scope block.read \
  --scope block.write \
  --scope bookmark.read \
  --scope bookmark.write \
  --scope dm.read \
  --scope dm.write \
  --authorization-endpoint https://x.com/i/oauth2/authorize \
  --token-endpoint https://api.x.com/2/oauth2/token

此默认示例包含了当前X OpenAPI提供的全部OAuth2用户权限范围，但未包含

offline.access

，以避免部分X应用配置中出现的刷新令牌兼容性问题。仅当您明确需要长期刷新功能且已验证您的应用支持令牌刷新时，才添加

--scope offline.access

参数。

在浏览器中打开返回的授权URL并完成授权同意。
使用回调URL完成登录：

bash

uxc auth oauth complete x-api-user \
  --session-id <session_id> \
  --authorization-response '<callback_url>'

将凭证绑定至X API：

bash

uxc auth binding add \
  --id x-api-user \
  --host api.x.com \
  --path-prefix /2 \
  --scheme https \
  --credential x-api-user \
  --priority 100

验证绑定：

bash

uxc auth binding match https://api.x.com/2

Optional Path: App-only Bearer Token (Public Reads)

可选方式：仅应用Bearer令牌（公开读取）

App-only bearer auth is useful for selected public read endpoints.

Do not embed bearer tokens in this skill or repository. Configure local credentials only.

bash

uxc auth credential set x-api-app \
  --auth-type bearer \
  --secret-env X_API_BEARER_TOKEN

uxc auth binding add \
  --id x-api-app \
  --host api.x.com \
  --path-prefix /2 \
  --scheme https \
  --credential x-api-app \
  --priority 90

Use

--auth x-api-app

when you intentionally want app-only requests.

仅应用Bearer认证适用于特定的公开读取接口。

请勿在本技能或代码库中嵌入Bearer令牌，仅在本地配置凭证。

bash

uxc auth credential set x-api-app \
  --auth-type bearer \
  --secret-env X_API_BEARER_TOKEN

uxc auth binding add \
  --id x-api-app \
  --host api.x.com \
  --path-prefix /2 \
  --scheme https \
  --credential x-api-app \
  --priority 90

当您明确需要仅应用请求时，使用

--auth x-api-app

参数。

Core Workflow

核心工作流

Use fixed link command by default:

```
command -v x-openapi-cli
```

If missing, create it:

uxc link x-openapi-cli https://api.x.com --schema-url https://api.x.com/2/openapi.json

```
x-openapi-cli -h
```

Inspect operation schema first:

```
x-openapi-cli get:/2/users/me -h
```

x-openapi-cli get:/2/users/{id}/bookmarks -h

```
x-openapi-cli post:/2/tweets -h
```

Execute reads before writes:

```
x-openapi-cli get:/2/users/me
```

x-openapi-cli get:/2/users/{id}/bookmarks id=<user_id> max_results=20

x-openapi-cli get:/2/users/{id}/timelines/reverse_chronological id=<user_id> max_results=20

Execute writes with explicit user confirmation:

key/value:

x-openapi-cli post:/2/tweets text='hello from uxc'

positional JSON:

x-openapi-cli post:/2/tweets '{"text":"hello from uxc"}'

默认使用固定链接命令：

```
command -v x-openapi-cli
```

若未找到，创建链接：

uxc link x-openapi-cli https://api.x.com --schema-url https://api.x.com/2/openapi.json

```
x-openapi-cli -h
```

先查看操作Schema：

```
x-openapi-cli get:/2/users/me -h
```

x-openapi-cli get:/2/users/{id}/bookmarks -h

```
x-openapi-cli post:/2/tweets -h
```

先执行读取操作，再执行写入操作：

```
x-openapi-cli get:/2/users/me
```

x-openapi-cli get:/2/users/{id}/bookmarks id=<user_id> max_results=20

x-openapi-cli get:/2/users/{id}/timelines/reverse_chronological id=<user_id> max_results=20

执行写入操作时需用户明确确认：

键值对形式：

x-openapi-cli post:/2/tweets text='hello from uxc'

位置参数JSON形式：

x-openapi-cli post:/2/tweets '{"text":"hello from uxc"}'

Subscribe / Stream Status

订阅/流状态

X stream endpoints are HTTP streaming routes and can be used with

uxc subscribe

raw HTTP stream mode.

Example:

bash

uxc subscribe start https://api.x.com/2/tweets/search/stream \
  --auth x-api-app \
  --sink file:$HOME/.uxc/subscriptions/x-search-stream.ndjson

Use the relevant stream rule-management endpoints before starting stream consumers.

X的流接口属于HTTP流路由，可与

uxc subscribe

原生HTTP流模式配合使用。

示例：

bash

uxc subscribe start https://api.x.com/2/tweets/search/stream \
  --auth x-api-app \
  --sink file:$HOME/.uxc/subscriptions/x-search-stream.ndjson

启动流消费前，请先使用相关的流规则管理接口。

Guardrails

约束规则

Keep automation on JSON output envelope; do not use
```
--text
```
.
Parse stable fields first:
```
ok
```
,
```
kind
```
,
```
protocol
```
,
```
data
```
,
```
error
```
.

x-openapi-cli <operation> ...

is equivalent to

uxc https://api.x.com --schema-url https://api.x.com/2/openapi.json <operation> ...

OAuth2 PKCE is the default path for user-context operations.
Do not commit or hardcode bearer tokens, client secrets, or refresh tokens.
Treat
```
post:/2/tweets
```
, DM endpoints, bookmark write endpoints, and stream rule mutation endpoints as write/high-risk operations; require explicit user confirmation before execution.

自动化操作需基于JSON输出格式，请勿使用
```
--text
```
参数。
优先解析稳定字段：
```
ok
```
、
```
kind
```
、
```
protocol
```
、
```
data
```
、
```
error
```
。

x-openapi-cli <operation> ...

等同于

uxc https://api.x.com --schema-url https://api.x.com/2/openapi.json <operation> ...

。

OAuth2 PKCE是用户上下文操作的默认方式。
请勿提交或硬编码Bearer令牌、客户端密钥或刷新令牌。
将
```
post:/2/tweets
```
、私信接口、书签写入接口及流规则修改接口视为写入/高风险操作，执行前需用户明确确认。

References

参考资料

Usage patterns:
```
references/usage-patterns.md
```
X API OpenAPI schema:
```
https://api.x.com/2/openapi.json
```

X OAuth2 authorization code with PKCE:

https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code

X OAuth2 app-only bearer auth:

https://docs.x.com/fundamentals/authentication/oauth-2-0/application-only

使用模式：
```
references/usage-patterns.md
```
X API OpenAPI Schema：
```
https://api.x.com/2/openapi.json
```

X OAuth2授权码+PKCE：

https://docs.x.com/fundamentals/authentication/oauth-2-0/authorization-code

X OAuth2仅应用Bearer认证：

https://docs.x.com/fundamentals/authentication/oauth-2-0/application-only