# Endpoint Reference

The server covers the Apidance docs `twitter-api` menu only.

Use either:

- `apidance_call` with `endpoint`.
- A generated endpoint tool named `twitter_<endpoint_id>`.

For example, these are equivalent:

```json
{
  "endpoint": "simple_search",
  "query": {
    "q": "eth"
  }
}
```

```json
{
  "q": "eth"
}
```

when sent to tool `twitter_simple_search`.

## Common Arguments

| Argument | Description |
| --- | --- |
| `api_key` | Optional per-call override for `APIDANCE_API_KEY`. Sent as header `apikey`. |
| `auth_token` | Optional per-call override for `APIDANCE_AUTH_TOKEN`. Sent as header `AuthToken`. |
| `use_proxy` | Optional per-call override for `APIDANCE_USE_PROXY`. Sent as header `UseProxy`. |
| `timeout_ms` | Per-call timeout in milliseconds. |
| `extra_headers` | Additional headers. |
| `query` | Query params for GET endpoints. Objects are JSON-stringified. |
| `variables` | Convenience GraphQL variables object. For GET it becomes query param `variables`; for POST it becomes JSON body `{ "variables": ... }` when `body` is omitted. |
| `features` | Convenience GraphQL features object for GET endpoints. |
| `body` | JSON body for POST endpoints. |
| `path_params` | Path params for endpoints such as `remaining_calls` and `custom_api_endpoint`. |

## 1.1

| Endpoint id | Tool | Method | Path | Notes |
| --- | --- | --- | --- | --- |
| `v11_users_show` | `twitter_v11_users_show` | GET | `/1.1/users/show.json` | Use `screen_name` or `user_id`. |
| `v11_followers_list` | `twitter_v11_followers_list` | GET | `/1.1/followers/list.json` | Use `screen_name` or `user_id`. |
| `v11_friends_list` | `twitter_v11_friends_list` | GET | `/1.1/friends/list.json` | Use `screen_name` or `user_id`. |

## GraphQL

| Endpoint id | Tool | Method | Path |
| --- | --- | --- | --- |
| `graphql_create_tweet` | `twitter_graphql_create_tweet` | POST | `/graphql/CreateTweet` |
| `graphql_create_note_tweet` | `twitter_graphql_create_note_tweet` | POST | `/graphql/CreateNoteTweet` |
| `graphql_create_retweet` | `twitter_graphql_create_retweet` | POST | `/graphql/CreateRetweet` |
| `graphql_quote_tweet` | `twitter_graphql_quote_tweet` | POST | `/graphql/CreateTweet` |
| `graphql_favorite_tweet` | `twitter_graphql_favorite_tweet` | POST | `/graphql/FavoriteTweet` |
| `graphql_create_bookmark` | `twitter_graphql_create_bookmark` | POST | `/graphql/CreateBookmark` |
| `graphql_home_latest_timeline` | `twitter_graphql_home_latest_timeline` | GET | `/graphql/HomeLatestTimeline` |
| `graphql_search_timeline` | `twitter_graphql_search_timeline` | GET | `/graphql/SearchTimeline` |
| `graphql_audio_space_search` | `twitter_graphql_audio_space_search` | GET | `/graphql/AudioSpaceSearch` |
| `graphql_audio_space_by_id` | `twitter_graphql_audio_space_by_id` | GET | `/graphql/AudioSpaceById` |
| `graphql_tweet_detail` | `twitter_graphql_tweet_detail` | GET | `/graphql/TweetDetail` |
| `graphql_tweet_result_by_rest_id` | `twitter_graphql_tweet_result_by_rest_id` | GET | `/graphql/TweetResultByRestId` |
| `graphql_user_by_screen_name` | `twitter_graphql_user_by_screen_name` | GET | `/graphql/UserByScreenName` |
| `graphql_user_by_rest_id` | `twitter_graphql_user_by_rest_id` | GET | `/graphql/UserByRestId` |
| `graphql_user_tweets` | `twitter_graphql_user_tweets` | GET | `/graphql/UserTweets` |
| `graphql_user_tweets_and_replies` | `twitter_graphql_user_tweets_and_replies` | GET | `/graphql/UserTweetsAndReplies` |
| `graphql_user_media` | `twitter_graphql_user_media` | GET | `/graphql/UserMedia` |
| `graphql_followers` | `twitter_graphql_followers` | GET | `/graphql/Followers` |
| `graphql_following` | `twitter_graphql_following` | GET | `/graphql/Following` |
| `graphql_followers_you_know` | `twitter_graphql_followers_you_know` | GET | `/graphql/FollowersYouKnow` |
| `graphql_retweeters` | `twitter_graphql_retweeters` | GET | `/graphql/Retweeters` |
| `graphql_list_latest_tweets_timeline` | `twitter_graphql_list_latest_tweets_timeline` | GET | `/graphql/ListLatestTweetsTimeline` |
| `graphql_profile_spotlights_query` | `twitter_graphql_profile_spotlights_query` | GET | `/graphql/ProfileSpotlightsQuery` |
| `graphql_communities_fetch_one_query` | `twitter_graphql_communities_fetch_one_query` | GET | `/graphql/CommunitiesFetchOneQuery` |
| `graphql_community_members` | `twitter_graphql_community_members` | GET | `/graphql/membersSliceTimeline_Query` |
| `graphql_community_tweets_timeline` | `twitter_graphql_community_tweets_timeline` | GET | `/graphql/CommunityTweetsTimeline` |
| `graphql_blue_verified_followers` | `twitter_graphql_blue_verified_followers` | GET | `/graphql/BlueVerifiedFollowers` |
| `graphql_ai_trend_by_rest_id` | `twitter_graphql_ai_trend_by_rest_id` | GET | `/graphql/AiTrendByRestId` |
| `graphql_trend_relevant_users` | `twitter_graphql_trend_relevant_users` | GET | `/graphql/TrendRelevantUsers` |
| `graphql_user_business_profile_team_timeline` | `twitter_graphql_user_business_profile_team_timeline` | GET | `/graphql/UserBusinessProfileTeamTimeline` |

GraphQL GET example:

```json
{
  "endpoint": "graphql_search_timeline",
  "variables": {
    "rawQuery": "twitter",
    "count": 40,
    "cursor": "",
    "querySource": "typed_query",
    "product": "Latest",
    "includePromotedContent": false
  }
}
```

TweetDetail article tweet example:

When querying an article tweet with `graphql_tweet_detail`, include `fieldToggles` as a query parameter at the same level as `variables` so the response can include rich article state and plain text content:

```json
{
  "endpoint": "graphql_tweet_detail",
  "variables": {
    "focalTweetId": "1694634492403843248",
    "referrer": "profile",
    "controller_data": "DAACDAABDAABCgABAAAAAAAAAAAKAAkAAAABFPY0+AAAAAA=",
    "with_rux_injections": false,
    "includePromotedContent": false,
    "withCommunity": true,
    "withQuickPromoteEligibilityTweetFields": true,
    "withBirdwatchNotes": true,
    "withVoice": true,
    "withV2Timeline": true
  },
  "fieldToggles": {
    "withArticleRichContentState": true,
    "withArticlePlainText": true
  }
}
```

Business profile affiliated accounts example:

```json
{
  "endpoint": "graphql_user_business_profile_team_timeline",
  "variables": {
    "userId": "783214",
    "cursor": "",
    "count": 100,
    "teamName": "NotAssigned",
    "includePromotedContent": false,
    "withClientEventToken": false,
    "withVoice": true
  }
}
```

`graphql_create_bookmark` follows the official Markdown body shape and sends the JSON body as `{ "tweet_id": "..." }`. You can either pass `body` directly or pass `variables`, which this MCP server maps to the root body for this endpoint.

GraphQL POST example:

```json
{
  "endpoint": "graphql_favorite_tweet",
  "auth_token": "your-auth-token-cookie-value",
  "variables": {
    "tweet_id": "1694634492403843248"
  }
}
```

## Simple API

| Endpoint id | Tool | Method | Path | Required query |
| --- | --- | --- | --- | --- |
| `simple_tweet_detail` | `twitter_simple_tweet_detail` | GET | `/sapi/TweetDetail` | `tweet_id` |
| `simple_user_tweets` | `twitter_simple_user_tweets` | GET | `/sapi/UserTweets` | `user_id` |
| `simple_retweeters` | `twitter_simple_retweeters` | GET | `/sapi/Retweeters` | `tweet_id` |
| `simple_quotes` | `twitter_simple_quotes` | GET | `/sapi/Quotes` | `tweet_id` |
| `simple_search` | `twitter_simple_search` | GET | `/sapi/Search` | `q` |

`cursor` is optional on these endpoints. `simple_search` also accepts `sort_by`; Apidance documents the default as `Latest`.

## Notifications

| Endpoint id | Tool | Method | Path |
| --- | --- | --- | --- |
| `notifications_all` | `twitter_notifications_all` | GET | `/2/notifications/all.json` |
| `notifications_mentions` | `twitter_notifications_mentions` | GET | `/2/notifications/mentions.json` |
| `notifications_verified` | `twitter_notifications_verified` | GET | `/2/notifications/verified.json` |

These endpoints are marked `developing` in Apidance docs and usually need `AuthToken`.

## Upload, Key, and Custom

| Endpoint id | Tool | Method | Path | Notes |
| --- | --- | --- | --- | --- |
| `upload_media` | `twitter_upload_media` | POST | `/twitter/upload` | Multipart form upload with field `file`. Use `file_path` or `file_base64`. |
| `remaining_calls` | `twitter_remaining_calls` | GET | `/key/{apikey}` | Uses `APIDANCE_API_KEY` for the path by default. |
| `custom_api_endpoint` | `twitter_custom_api_endpoint` | GET | `/graphql/{id}/{path}` | Pass `graphql_id` and `api_path`, or `path_params.id` and `path_params.path`. |

Custom endpoint example:

```json
{
  "endpoint": "custom_api_endpoint",
  "graphql_id": "api endpoint graphql id",
  "api_path": "api path",
  "variables": {
    "screen_name": "elonmusk"
  }
}
```

## Response Shape

All tools return JSON text:

```json
{
  "endpoint": {
    "id": "simple_search",
    "title": "Search",
    "category": "simple api",
    "method": "GET",
    "url": "https://api.apidance.pro/sapi/Search?q=eth",
    "docs_url": "https://doc.apidance.pro/search-11279446e0.md"
  },
  "status": 200,
  "ok": true,
  "headers": {
    "content-type": "application/json"
  },
  "data": {}
}
```

The server redacts `APIDANCE_API_KEY`, `APIDANCE_AUTH_TOKEN`, and `APIDANCE_USE_PROXY` from the returned request URL.