Skip to content

Commit bf0c7b2

Browse files
tcaldwell-xtcaldwell-x
committed
docs: add Enterprise plan requirement callouts to blocks endpoints
The block (POST) and unblock (DELETE) endpoints are Enterprise-only, but the docs presented them alongside the block lookup (GET) endpoint with no mention of this restriction, leading developers to believe they are available on pay-per-use. Changes across all four blocks content pages: - Add prominent Warning banners clarifying Enterprise requirements - Add Availability columns to endpoint and scope tables - Label Enterprise-only sections and code examples - Update error handling guidance for 403 responses - Reorder overview cards to lead with the universally available endpoint
1 parent edee238 commit bf0c7b2

File tree

4 files changed

+791
-758
lines changed

4 files changed

+791
-758
lines changed

‎x-api/users/blocks/integrate.mdx‎

Lines changed: 198 additions & 194 deletions
Original file line numberDiff line numberDiff line change
@@ -1,194 +1,198 @@
1-
---
2-
title: Integration Guide
3-
sidebarTitle: Integration Guide
4-
description: Key concepts and best practices for integrating blocks endpoints
5-
keywords: ["blocks integration", "block users integration", "blocks guide"]
6-
---
7-
8-
import { Button } from '/snippets/button.mdx';
9-
10-
This guide covers the key concepts you need to integrate the blocks endpoints into your application.
11-
12-
---
13-
14-
## Authentication
15-
16-
Blocks endpoints require user authentication:
17-
18-
| Method | Description |
19-
|:-------|:------------|
20-
| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recommended for new applications |
21-
| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy support |
22-
23-
<Warning>
24-
App-Only authentication is not supported. You must authenticate on behalf of a user.
25-
</Warning>
26-
27-
### Required scopes (OAuth 2.0)
28-
29-
| Scope | Required for |
30-
|:------|:-------------|
31-
| `block.read` | Retrieving blocked accounts |
32-
| `block.write` | Blocking and unblocking accounts |
33-
| `users.read` | Required with block scopes |
34-
35-
---
36-
37-
## Endpoints overview
38-
39-
| Method | Endpoint | Description |
40-
|:-------|:---------|:------------|
41-
| GET | `/2/users/:id/blocking` | Get list of blocked accounts |
42-
| POST | `/2/users/:id/blocking` | Block an account |
43-
| DELETE | `/2/users/:source_user_id/blocking/:target_user_id` | Unblock an account |
44-
45-
---
46-
47-
## Fields and expansions
48-
49-
### Default response
50-
51-
```json
52-
{
53-
"data": [
54-
{
55-
"id": "1234567890",
56-
"name": "Example User",
57-
"username": "example"
58-
}
59-
]
60-
}
61-
```
62-
63-
### Available fields
64-
65-
<Accordion title="user.fields">
66-
| Field | Description |
67-
|:------|:------------|
68-
| `created_at` | Account creation date |
69-
| `description` | User bio |
70-
| `profile_image_url` | Avatar URL |
71-
| `public_metrics` | Follower/following counts |
72-
| `verified` | Verification status |
73-
</Accordion>
74-
75-
<Accordion title="expansions">
76-
| Expansion | Description |
77-
|:----------|:------------|
78-
| `pinned_tweet_id` | User's pinned Post |
79-
</Accordion>
80-
81-
---
82-
83-
## What happens when you block
84-
85-
<CardGroup cols={2}>
86-
<Card title="They can't" icon="xmark">
87-
- See your Posts (unless logged out)
88-
- Follow you
89-
- Send you DMs
90-
- Add you to Lists
91-
- Tag you in photos
92-
</Card>
93-
<Card title="You can't" icon="xmark">
94-
- See their Posts
95-
- Follow them
96-
- Send them DMs
97-
</Card>
98-
</CardGroup>
99-
100-
<Note>
101-
When you block someone who follows you, they are automatically unfollowed.
102-
</Note>
103-
104-
---
105-
106-
## Pagination
107-
108-
For users with large block lists, results are paginated:
109-
110-
<CodeGroup dropdown>
111-
112-
```bash cURL
113-
# First request
114-
curl "https://api.x.com/2/users/123/blocking?max_results=100" \
115-
-H "Authorization: Bearer $USER_ACCESS_TOKEN"
116-
117-
# Subsequent request with pagination token
118-
curl "https://api.x.com/2/users/123/blocking?max_results=100&pagination_token=NEXT_TOKEN" \
119-
-H "Authorization: Bearer $USER_ACCESS_TOKEN"
120-
```
121-
122-
```python Python SDK
123-
from xdk import Client
124-
125-
# Use OAuth 2.0 user access token
126-
client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")
127-
128-
# The SDK handles pagination automatically
129-
all_blocked = []
130-
131-
for page in client.users.get_blocking(user_id="123", max_results=100):
132-
if page.data:
133-
all_blocked.extend(page.data)
134-
135-
print(f"Blocked {len(all_blocked)} users")
136-
```
137-
138-
```javascript JavaScript SDK
139-
import { Client } from "@xdevplatform/xdk";
140-
141-
const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });
142-
143-
async function getAllBlockedUsers(userId) {
144-
const allBlocked = [];
145-
146-
// The SDK handles pagination automatically
147-
const paginator = client.users.getBlocking(userId, { maxResults: 100 });
148-
149-
for await (const page of paginator) {
150-
if (page.data) {
151-
allBlocked.push(...page.data);
152-
}
153-
}
154-
155-
return allBlocked;
156-
}
157-
158-
// Usage
159-
const blocked = await getAllBlockedUsers("123");
160-
console.log(`Blocked ${blocked.length} users`);
161-
```
162-
163-
</CodeGroup>
164-
165-
---
166-
167-
## Error handling
168-
169-
| Status | Error | Solution |
170-
|:-------|:------|:---------|
171-
| 400 | Invalid request | Check user ID format |
172-
| 401 | Unauthorized | Verify access token |
173-
| 403 | Forbidden | Check scopes and permissions |
174-
| 404 | Not Found | User doesn't exist |
175-
| 429 | Too Many Requests | Wait and retry |
176-
177-
---
178-
179-
## Next steps
180-
181-
<CardGroup cols={2}>
182-
<Card title="Quickstart" icon="rocket" href="/x-api/users/blocks/quickstart">
183-
Make your first blocks request
184-
</Card>
185-
<Card title="Mutes" icon="volume-xmark" href="/x-api/users/mutes/introduction">
186-
Mute users instead of blocking
187-
</Card>
188-
<Card title="API Reference" icon="code" href="/x-api/users/get-blocking">
189-
Full endpoint documentation
190-
</Card>
191-
<Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
192-
Working code examples
193-
</Card>
194-
</CardGroup>
1+
---
2+
title: Integration Guide
3+
sidebarTitle: Integration Guide
4+
description: Key concepts and best practices for integrating blocks endpoints
5+
keywords: ["blocks integration", "block users integration", "blocks guide"]
6+
---
7+
8+
import { Button } from '/snippets/button.mdx';
9+
10+
This guide covers the key concepts you need to integrate the blocks endpoints into your application.
11+
12+
<Warning>
13+
**Enterprise plan required** — The block (`POST /2/users/:id/blocking`) and unblock (`DELETE /2/users/:source_user_id/blocking/:target_user_id`) endpoints are only available on the [Enterprise plan](/forms/enterprise-api-interest). The block lookup endpoint (`GET /2/users/:id/blocking`) is available on all plans, including pay-per-use.
14+
</Warning>
15+
16+
---
17+
18+
## Authentication
19+
20+
Blocks endpoints require user authentication:
21+
22+
| Method | Description |
23+
|:-------|:------------|
24+
| [OAuth 2.0 Authorization Code with PKCE](/resources/fundamentals/authentication#oauth-2-0-authorization-code-flow-with-pkce-2) | Recommended for new applications |
25+
| [OAuth 1.0a User Context](/resources/fundamentals/authentication) | Legacy support |
26+
27+
<Warning>
28+
App-Only authentication is not supported. You must authenticate on behalf of a user.
29+
</Warning>
30+
31+
### Required scopes (OAuth 2.0)
32+
33+
| Scope | Required for | Availability |
34+
|:------|:-------------|:-------------|
35+
| `block.read` | Retrieving blocked accounts | Pay-per-use, Enterprise |
36+
| `block.write` | Blocking and unblocking accounts | Enterprise only |
37+
| `users.read` | Required with block scopes | Pay-per-use, Enterprise |
38+
39+
---
40+
41+
## Endpoints overview
42+
43+
| Method | Endpoint | Description | Availability |
44+
|:-------|:---------|:------------|:-------------|
45+
| GET | `/2/users/:id/blocking` | Get list of blocked accounts | Pay-per-use, Enterprise |
46+
| POST | `/2/users/:id/blocking` | Block an account | Enterprise only |
47+
| DELETE | `/2/users/:source_user_id/blocking/:target_user_id` | Unblock an account | Enterprise only |
48+
49+
---
50+
51+
## Fields and expansions
52+
53+
### Default response
54+
55+
```json
56+
{
57+
"data": [
58+
{
59+
"id": "1234567890",
60+
"name": "Example User",
61+
"username": "example"
62+
}
63+
]
64+
}
65+
```
66+
67+
### Available fields
68+
69+
<Accordion title="user.fields">
70+
| Field | Description |
71+
|:------|:------------|
72+
| `created_at` | Account creation date |
73+
| `description` | User bio |
74+
| `profile_image_url` | Avatar URL |
75+
| `public_metrics` | Follower/following counts |
76+
| `verified` | Verification status |
77+
</Accordion>
78+
79+
<Accordion title="expansions">
80+
| Expansion | Description |
81+
|:----------|:------------|
82+
| `pinned_tweet_id` | User's pinned Post |
83+
</Accordion>
84+
85+
---
86+
87+
## What happens when you block
88+
89+
<CardGroup cols={2}>
90+
<Card title="They can't" icon="xmark">
91+
- See your Posts (unless logged out)
92+
- Follow you
93+
- Send you DMs
94+
- Add you to Lists
95+
- Tag you in photos
96+
</Card>
97+
<Card title="You can't" icon="xmark">
98+
- See their Posts
99+
- Follow them
100+
- Send them DMs
101+
</Card>
102+
</CardGroup>
103+
104+
<Note>
105+
When you block someone who follows you, they are automatically unfollowed.
106+
</Note>
107+
108+
---
109+
110+
## Pagination
111+
112+
For users with large block lists, results are paginated:
113+
114+
<CodeGroup dropdown>
115+
116+
```bash cURL
117+
# First request
118+
curl "https://api.x.com/2/users/123/blocking?max_results=100" \
119+
-H "Authorization: Bearer $USER_ACCESS_TOKEN"
120+
121+
# Subsequent request with pagination token
122+
curl "https://api.x.com/2/users/123/blocking?max_results=100&pagination_token=NEXT_TOKEN" \
123+
-H "Authorization: Bearer $USER_ACCESS_TOKEN"
124+
```
125+
126+
```python Python SDK
127+
from xdk import Client
128+
129+
# Use OAuth 2.0 user access token
130+
client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")
131+
132+
# The SDK handles pagination automatically
133+
all_blocked = []
134+
135+
for page in client.users.get_blocking(user_id="123", max_results=100):
136+
if page.data:
137+
all_blocked.extend(page.data)
138+
139+
print(f"Blocked {len(all_blocked)} users")
140+
```
141+
142+
```javascript JavaScript SDK
143+
import { Client } from "@xdevplatform/xdk";
144+
145+
const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });
146+
147+
async function getAllBlockedUsers(userId) {
148+
const allBlocked = [];
149+
150+
// The SDK handles pagination automatically
151+
const paginator = client.users.getBlocking(userId, { maxResults: 100 });
152+
153+
for await (const page of paginator) {
154+
if (page.data) {
155+
allBlocked.push(...page.data);
156+
}
157+
}
158+
159+
return allBlocked;
160+
}
161+
162+
// Usage
163+
const blocked = await getAllBlockedUsers("123");
164+
console.log(`Blocked ${blocked.length} users`);
165+
```
166+
167+
</CodeGroup>
168+
169+
---
170+
171+
## Error handling
172+
173+
| Status | Error | Solution |
174+
|:-------|:------|:---------|
175+
| 400 | Invalid request | Check user ID format |
176+
| 401 | Unauthorized | Verify access token |
177+
| 403 | Forbidden | Check scopes, permissions, and plan access. Block/unblock endpoints require an [Enterprise plan](/forms/enterprise-api-interest) |
178+
| 404 | Not Found | User doesn't exist |
179+
| 429 | Too Many Requests | Wait and retry |
180+
181+
---
182+
183+
## Next steps
184+
185+
<CardGroup cols={2}>
186+
<Card title="Quickstart" icon="rocket" href="/x-api/users/blocks/quickstart">
187+
Make your first blocks request
188+
</Card>
189+
<Card title="Mutes" icon="volume-xmark" href="/x-api/users/mutes/introduction">
190+
Mute users instead of blocking
191+
</Card>
192+
<Card title="API Reference" icon="code" href="/x-api/users/get-blocking">
193+
Full endpoint documentation
194+
</Card>
195+
<Card title="Sample code" icon="github" href="https://github.com/xdevplatform/Twitter-API-v2-sample-code">
196+
Working code examples
197+
</Card>
198+
</CardGroup>

0 commit comments

Comments
 (0)