Documentation Index
Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt
Use this file to discover all available pages before exploring further.
Available
BYOK connector - Twitter requires you to bring your own Twitter Developer app. Setup takes about ten minutes. See Platform credentials for why Twitter is the only platform that works this way.
At a glance
| Field | Value |
|---|
| Platform slug | twitter |
| Auth type | OAuth 2.0 (BYOK) |
| API | X API v2 |
| Best for | Real-time conversation: tweets, replies, DMs, mentions on X. |
Setup
Before you can connect any Twitter account, register a Twitter Developer app and paste your Client ID and Client Secret into your SocialAPI dashboard. See the Twitter BYOK setup guide for the ten-minute walkthrough.
Capabilities
| Feature | Supported | Notes |
|---|
| List posts | Yes | Returns user tweets |
| Comments | Yes | Replies to a specific tweet |
| Reply to comment | Yes | |
| Comment replies (thread) | Yes | |
| Moderate comment (hide/delete) | Yes | Hide a reply, or delete your own reply |
| Like comment | No | X removed like/unlike writes from self-serve tiers (Enterprise only) |
| Private reply | No | Not applicable |
| DMs | Yes | Direct Messages via X API v2 |
| Send DM | Yes | |
| Reviews | No | Not applicable |
| Mentions | Yes | Tweets mentioning the authenticated user |
| Create post | Yes | Text tweets only (no media upload today) |
| Update post | No | Edits are gated to Enterprise; not available to self-serve apps |
| Delete post | Yes | |
Connecting
curl -X POST https://api.social-api.ai/v1/accounts/connect \
-H "Authorization: Bearer $SOCAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "twitter",
"redirect_uri": "https://app.example.com/oauth/callback",
"state": "session_abc123"
}'
{
"auth_url": "https://x.com/i/oauth2/authorize?client_id=...&state=...",
"state": "4a8f2c1e9b3d7f06a5c2e8b4d1f3a7e2"
}
auth_url. After they authorize, SocialAPI exchanges the code with X and redirects the user to your redirect_uri with the connection result. See OAuth flows for the redirect parameters.
Reading samples
List posts
curl "https://api.social-api.ai/v1/posts?account_ids={id}&limit=10" \
-H "Authorization: Bearer $SOCAPI_KEY"
curl "https://api.social-api.ai/v1/accounts/{id}/posts/{pid}/comments?limit=10" \
-H "Authorization: Bearer $SOCAPI_KEY"
List DMs
curl "https://api.social-api.ai/v1/inbox/conversations?account_id={id}" \
-H "Authorization: Bearer $SOCAPI_KEY"
List mentions
curl "https://api.social-api.ai/v1/accounts/{id}/mentions?limit=10" \
-H "Authorization: Bearer $SOCAPI_KEY"
Publishing
Create a tweet with optional X-specific settings:
curl -X POST https://api.social-api.ai/v1/posts \
-H "Authorization: Bearer $SOCAPI_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello from SocialAPI!",
"targets": [
{
"account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
"platform_data": {
"reply_settings": "following"
}
}
]
}'
platform_data when creating a post. All fields are optional.
| Field | Type | Description |
|---|
reply_settings | string | Who can reply to this tweet. One of "following", "mentionedUsers", "subscribers", "verified". |
geo_place_id | string | Attach a location by X place ID. |
community_id | string | Post into an X Community. |
for_super_followers_only | boolean | Restrict the post to Super Followers. |
nullcast | boolean | Promoted-only post (does not appear in the timeline). |
made_with_ai | boolean | Flag the post as AI-generated content. |
paid_partnership | boolean | Disclose branded content. |
in_reply_to_tweet_id | string | Publish the post as a reply to an existing tweet. |
auto_populate_reply_metadata | boolean | Auto-include @mentions from the tweet being replied to. Only meaningful with in_reply_to_tweet_id. |
exclude_reply_user_ids | array of string | User IDs to exclude from auto-populated @mentions. Only meaningful with in_reply_to_tweet_id. |
thread | array of string | Continuation tweets chained after the root, posted in order. See Threads. |
reply_settings enum, a wrong field type, an empty or over-length thread entry) are rejected by POST /v1/posts/validate and by create with a validation error, before any tweet is published. Unrecognized platform_data keys are ignored with a warning.
Threads
Set thread to an array of strings to publish a chained thread. The target’s text is the root tweet (tweet 1) and each thread entry is posted as a reply to the one before it. Continuation tweets are text-only: the platform_data settings above apply to the root tweet only.
{
"text": "1/ A thread about our launch.",
"targets": [
{
"account_id": "acc_01HZ9X3Q4R5M6N7P8V2K0W1J",
"platform_data": {
"thread": [
"2/ First, the backstory.",
"3/ And here is what is next."
]
}
}
]
}
thread_post_ids. If a continuation tweet fails partway through, publishing stops: the tweets posted so far stay live (X has no batch rollback), the metadata records thread_failed_at_index, and the request returns an error.
Each tweet in a thread is a separate billable X write. Posts containing a URL cost significantly more per X’s pay-per-use pricing, so keep links minimal.
Limitations and gotchas
- Text-only posts. Posts carry text plus the
platform_data settings above, and can be chained into threads. Media upload is not implemented yet, so image and video attachments are ignored. Polls and quote tweets are also unsupported.
- No post editing. X’s edit capability (
edit_options.previous_post_id) is gated to Enterprise on the pay-per-use tier, so it is not available to self-serve BYOK apps. UpdatePost returns 501. Delete and re-create if needed.
- No webhook handler. X does not push real-time events via this integration. Posts and comments are fetched on demand.
- Comment moderation. Hide toggles reply visibility. Delete removes your own replies. Liking is not available: X removed like/unlike writes from all self-serve tiers (April 2026), so
can_like is false.
- Token refresh. X OAuth 2.0 tokens expire after two hours. SocialAPI handles refresh automatically. If you receive
401 with code: "invalid_token", reconnect the account.
- Required scopes. Your X Developer App must have the appropriate OAuth 2.0 scopes for reading tweets, posting, DMs, and user lookup.
Permissions
Because Twitter is BYOK, you control the OAuth scopes on your own Twitter Developer app. We recommend enabling these scopes for full functionality: read and write tweets, read and send DMs, user lookup. See the Twitter BYOK setup guide for the exact scope list to select in the X Developer Portal.
