X Ads API creatives: the 30 endpoints with no heading
The X Ads API creatives reference documents 49 endpoints but gives only 19 a heading. Here is the full inventory, including every PUT and DELETE it hides.
On this page · 8 sections
- Quick answer
- What is actually in the namespace
- The links are broken in a way you can count
- The card_types filter cannot filter for most card types
- Cards Fetch is a section for an endpoint that will not see your cards
- The create path, in the order that actually works
- Is this namespace worth the integration?
- The bottom line
The short version
- ▸The Creatives API Reference documents 49 endpoints, counted by resource URL block: 22 GET, 10 POST, 8 PUT and 9 DELETE. Only 19 of them get a heading, and every one of the 17 update and delete endpoints is headless, buried inside a POST section.
- ▸Because they have no headings, they have no anchors. The Creatives guide deep-links into that reference 12 times and 11 of the 12 anchors do not exist on the page. The reference links to itself 26 times and 13 of those miss. Every Resource URL and Example Request permalink on the page is dead: 98 links to anchor ids the page never defines.
- ▸The card_types filter on GET cards accepts 13 values. The page's own example responses return 9 card types, and only 3 of those 9 are in the enum. Conversation cards and poll cards show up in 18 examples and cannot be filtered for at all.
- ▸GET cards/all still has its own section, but X stated on 19 November 2020 that cards created with the current POST cards endpoint are not returned by it. Neither the guide nor the reference repeats that, and the Cards Fetch examples return VIDEO_WEBSITE, a card type the same announcement scheduled to sunset on 31 August 2021.
- ▸The PUT cards resource URL is written as accounts/:account_id/cards/1321554298900107264 - a literal card id from the example response, pasted where :card_id belongs. Every other section in the file parameterises it.
Quick answer
The X Ads API creatives namespace is bigger than its documentation looks. The Creatives API Reference contains 49 endpoints, counted by resource URL block, but only 19 of them have a heading. The 30 that do not include all 8 PUT endpoints and all 9 DELETE endpoints, so every update and delete path in the namespace is invisible to the page's own navigation, to its table of contents, and to anything that scrapes headings. The links are worse: of 38 deep links into that reference from X's own pages, 24 point at anchors that do not exist.
Last updated: November 2026
If you are wiring up ad creative on X (formerly Twitter) and cannot find how to edit a card, you have not missed a page. The endpoint is there. It just has no heading.
What is actually in the namespace
Here is the full inventory, extracted from the reference's resource URL blocks on 14 November 2026. Rows marked with a dot are the ones with a heading on the page.
| Family | Endpoints | Verbs |
|---|---|---|
| Account Media | 3 | GET list (dot), GET by id, DELETE |
| Cards | 5 | GET list, GET by id, POST (dot), PUT, DELETE |
| Cards Fetch | 2 | GET cards/all, GET cards/all/:card_id |
| Draft Tweets | 6 | GET list (dot), GET by id, POST (dot), PUT, DELETE, POST preview (dot) |
| Image Conversation Cards | 5 | GET list (dot), GET by id, POST (dot), PUT, DELETE |
| Media Library | 5 | GET list (dot), GET by id, POST, PUT, DELETE |
| Poll Cards | 4 | GET list (dot), GET by id, POST (dot), DELETE |
| Preroll Call To Actions | 5 | GET list (dot), GET by id, POST (dot), PUT, DELETE |
| Scheduled Tweets | 5 | GET list (dot), GET by id, POST (dot), PUT, DELETE |
| Tweet Previews | 1 | GET (dot) |
| Tweets | 3 | GET list (dot), POST tweet (dot), PUT tweets/:tweet_id/name |
| Video Conversation Cards | 5 | GET list (dot), GET by id, POST (dot), PUT, DELETE |
Three things fall out of that table immediately.
Account Media has no POST. You can list it, look one up and delete one, but you cannot create account media through the API. Its creative_types enum gives away why: BANNER, BANNER_TABLET, INTERSTITIAL, INTERSTITIAL_LANDSCAPE, INTERSTITIAL_LANDSCAPE_TABLET, INTERSTITIAL_TABLET, MEDIUM_RECTANGLE, PREROLL and VAST_PREROLL. These are mobile-app ad slots and preroll inventory, loaded elsewhere. For anything you want to attach to a post, the Media Library is the right family.
Poll cards have no PUT. Every other card family has one. A poll card, once created, can be read or deleted and nothing else, which makes sense given duration_in_minutes starts running, but it is worth knowing before you design an edit screen around it.
The only write on Tweets is a rename. PUT accounts/:account_id/tweets/:tweet_id/name changes the internal name of a promoted post, not its content. Promoted post content is immutable, same as organic.
The links are broken in a way you can count
This is not a style complaint. It changes how you have to read the docs.
The Creatives guide deep-links into the reference 12 times, with anchors like #get-accounts-account-id-scheduled-tweets. The reference's real anchors are shaped differently: #get-accounts/account_id/scheduled_tweets, with slashes and underscores preserved. Eleven of the 12 anchors therefore resolve to nothing, and only #video-conversation-cards lands where it says. Two of those 12 are the PUT and DELETE for scheduled tweets, and they point at #example-request-39 and #example-request-40, auto-numbered anchors that do not exist anywhere on the page.
Inside the reference it is the same story: 26 self-links, of which 13 hit #media-library and work, and the other 13 miss, including the "see our Carousels Guide" pointer that aims at #carousels on a page with no carousels section.
Then there are the permalinks. Each of the 49 endpoint blocks renders a Resource URL and an Example Request label with a clickable permalink next to it. All 49 Resource URL links point at #resource-url and all 49 Example Request links point at #example-request, and the page defines neither id. That is 98 dead in-page links on one reference page.
Finally, 36 outbound links in the creatives doc set still point at developer.x.com, the retired developer portal, across 29 distinct URLs. Every one of them 307-redirects to a homepage rather than a documented endpoint. If you want the Media Library POST, the guide's link for it is developer.x.com/x-ads-api/creatives/reference#get-accounts-account-id-media-library#post-accounts-account-id-media-library, with two fragment identifiers in one URL, on a host that will not serve it.
The practical rule: ignore every link in the creatives docs and search the reference page text instead. Grep is the navigation.
The card_types filter cannot filter for most card types
GET accounts/:account_id/cards accepts a card_types enum with 13 values, all of them website, app or carousel variants: IMAGE_APP, IMAGE_CAROUSEL_APP, IMAGE_CAROUSEL_WEBSITE, IMAGE_MULTI_DEST_CAROUSEL_WEBSITE, IMAGE_WEBSITE, MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE, VIDEO_APP, VIDEO_CAROUSEL_APP, VIDEO_CAROUSEL_WEBSITE, VIDEO_MULTI_DEST_CAROUSEL_WEBSITE and VIDEO_WEBSITE.
Against that, the same page's example responses return nine distinct card_type values, and only three of them are in that list. The six that are not: IMAGE_APP_DOWNLOAD, IMAGE_CONVERSATION, IMAGE_POLLS, TEXT_POLLS, VIDEO_CONVERSATION and VIDEO_POLLS. Conversation cards alone account for 14 of the example responses on the page, and poll cards for another four. Both families have their own dedicated POST endpoints in the same file. Neither can be requested through the filter that exists to request card types.
So if you are syncing cards and want only conversation cards, you cannot ask the unified endpoint for them. Use GET accounts/:account_id/cards/image_conversation and GET accounts/:account_id/cards/video_conversation, which are the per-family list endpoints, and filter client-side on anything else.
Cards Fetch is a section for an endpoint that will not see your cards
X still gives GET accounts/:account_id/cards/all its own section in the reference, named Cards Fetch, with two documented endpoints and two example responses.
On 19 November 2020, X's Ads API account posted that cards created using the then-new POST accounts/:account_id/cards endpoint "are not available via the GET accounts/:account_id/cards/all endpoint." That POST is the only card create endpoint the current docs recommend. The caveat has never been added to either the guide or the reference, and the forum thread where it lives has had no staff update since 21 July 2021.
Its example responses make the age visible. Both return card_type: VIDEO_WEBSITE, one of the four legacy resources - website cards, video website cards, image app download cards, video app cards - that the same 2020 announcement said were "expected to sunset with v8, on August 31, 2021." The reference is on /12/, current since 27 October 2022, and still illustrating cards/all with a card type retired over five years ago.
What to do instead: read cards with GET accounts/:account_id/cards, and pass include_legacy_cards=true when you need the migrated website and app cards too. X completed that migration in 2021 and the flag is how you see the results.
The create path, in the order that actually works
Strip the broken links away and the happy path is short. It is the same four steps as X ads API campaigns, one level down.
- Upload the asset.
POST media/upload, or the chunked variant for video. This is the regular v2 media pipeline, covered in detail in our X API media upload walkthrough, not an Ads-specific route. - Add it to the Media Library.
POST accounts/:account_id/media_librarywith themedia_idfrom step 1 plus amedia_category, which must be one ofAMPLIFY_VIDEO,TWEET_GIF,TWEET_IMAGEorTWEET_VIDEO. You get back amedia_keyshaped like13_875943225764098048. Setnameandfile_namehere, because the library is the only place you can tell two near-identical assets apart later. - Create the card.
POST accounts/:account_id/cards, JSON body only,Content-Type: application/json. Required: anameof at most 80 characters, and either acomponentsarray or aslidesarray. The two are mutually exclusive, andslidesexists only for multi-destination carousels. Component order matters. There are exactly four component types:MEDIA(onemedia_key),SWIPEABLE_MEDIA(2 to 6media_keys, which is also the carousel range),DETAILS(atitleand adestination) andBUTTON(alabeland adestination). - Create the post, then promote it.
POST accounts/:account_id/tweetwithcard_uriandnullcastset true for an ad that never hits your public timeline, then promote through Campaign Management.
Two extras worth knowing. POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id sends a push notification to every device the authenticated user is logged in to, opening a timeline where the draft behaves like a live post so you can test autoplay, volume and card docking. It only reaches official X apps, and only the user who receives it can see it. And DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id is documented as a hard delete with no recovery, unlike most Ads API objects where with_deleted=true brings things back into a read.
If you only need to check how a link renders rather than build a card, our X card validator guide covers the preview route that does not require Ads API access at all.
Is this namespace worth the integration?
Honestly, it depends what you are automating.
If you are building paid ad creative at volume, yes, and there is no alternative: this is the only sanctioned way to create cards programmatically, and the component model genuinely is more flexible than the per-type endpoints it replaced. Budget time for the docs, not the code. The endpoints behave; the page describing them is five years stale in places.
If you are shipping a product catalog, look at X dynamic product ads first, because the catalog path generates creative for you and has a different access gate. And if you want a faster route into all of this, X's hosted MCP servers wrap the Ads API in tools rather than endpoints, which our X MCP server guide walks through.
If what you actually want is the organic side of the same account posting on schedule, this is the wrong API. X-Autopilot runs locally on your Mac with your own session and residential IP rather than a shared cloud pool, which lowers the detection surface compared with cloud schedulers without removing it. Browser-driven automation of your own account is a gray area that X has never endorsed, and we will not tell you otherwise. The Ads API is the opposite: approved, rate limited in writing, and billed to a funding instrument you set up by hand. Different route, different risk, and worth being clear about which one you are on.
The bottom line
The X Ads API creatives namespace has 49 endpoints and 19 headings. Everything that modifies or removes a creative is in the second group. Once you know that, the reference is usable: open it as raw markdown by appending .md to the URL, search for the resource path you want, and read the unheaded block underneath it. What you should not do is trust the navigation, the anchors, or the example responses, three of which still describe a card type that stopped existing in 2021.
Frequently asked
Answers indexed by Google + AI assistants.
How many endpoints are in the X Ads API creatives namespace?+
49, if you count resource URL blocks on the Creatives API Reference: 22 GET, 10 POST, 8 PUT and 9 DELETE across 12 resource families. The page only gives 19 of them a heading, which is why most endpoint counts you see for this namespace are closer to 19. The gap is entirely writes. All 8 PUT endpoints and all 9 DELETE endpoints are documented as unheaded prose inside the matching POST section.
How do I update a card through the X Ads API?+
PUT accounts/:account_id/cards/:card_id, with a JSON body and Content-Type set to application/json. You will not find it by navigation, because it has no heading and no anchor. Note that X's own resource URL for this endpoint has a literal card id baked into it (accounts/:account_id/cards/1321554298900107264), copied from the example above it. Substitute your own card id. Poll cards are the exception with no PUT at all: once a poll card exists you can only read or delete it.
What is the difference between media_key and media_id in the X Ads API?+
media_key is the Media Library identifier, a string shaped like 13_875943225764098048, and it is accepted by the card endpoints. media_id is the older numeric upload identifier. The Media Library guide says the response includes media_id because Tweets, Tweet preview and Scheduled Tweets do not accept media keys, but that is stale: the current reference documents a media_keys parameter on POST tweet, POST draft_tweets and POST scheduled_tweets. Use media_keys and keep media_id as a fallback.
Can I add media to account_media through the X Ads API?+
No. The Account Media family has two GET endpoints and a DELETE, and no POST. You can list account media, look one up, and delete one, but creating it is not an API operation. The nine creative_types it reports (BANNER, BANNER_TABLET, INTERSTITIAL and its three variants, MEDIUM_RECTANGLE, PREROLL and VAST_PREROLL) are mobile-app and preroll ad slots, not post media. For anything you want to attach to a post, use the Media Library instead.
Why does GET cards/all not return my new cards?+
Because it never did. X's Ads API announcement of 19 November 2020 stated that cards created using the new POST accounts/:account_id/cards endpoint are not available via GET accounts/:account_id/cards/all. That caveat lives only in that five-year-old forum post. The Cards Fetch section of the current v12 reference repeats none of it, and its two example responses return card_type VIDEO_WEBSITE, one of the legacy resources the same announcement said would sunset with v8 on 31 August 2021. Read new cards with GET accounts/:account_id/cards, and pass include_legacy_cards=true when you also need the migrated website and app cards.
What are the rate limits on the X Ads API creatives endpoints?+
There is no per-endpoint row for creatives. Writes across the whole Ads API share one category bucket of 450 requests per minute, and reads with an :account_id in the path fall under account-level limits of 10,000 for core entity reads or 2,000 per 15 minutes for everything else. One creatives-specific trap: five of the list endpoints accept with_total_count, and X notes that requests including total_count are limited to 200 per 15 minutes and cannot be combined with cursor.
- X developer docs, 'Creatives API Reference': the 49 resource URL blocks across 12 families, the 13-value card_types enum, the 9-value creative_types enum, the literal card id in the PUT cards resource URL, the 80-character name limit, the MEDIA / SWIPEABLE_MEDIA / DETAILS / BUTTON component types, and the total_count note capping those requests at 200 per 15 minutes (fetched and parsed 14 November 2026)
- X developer docs, Ads API 'Creatives' guide: the scheduled tweet endpoint list including the PUT and DELETE paths, the two-step Media Library upload, the four media_category values, the media_key format, the statement that Tweets and Scheduled Tweets do not accept media keys, and the 2 to 6 asset carousel range (fetched 14 November 2026)
- X Developers forum, Ads API announcement 'New Cards Endpoints and Carousel Ads', posted 19 November 2020 and last updated 21 July 2021: the component-based POST cards endpoint, the four legacy card resources scheduled to sunset with v8 on 31 August 2021, the statement that new cards are not available via GET cards/all, the 200 card_uris limit added 27 January 2021, and include_legacy_cards
- X developer docs, Ads API 'Versions': version 12 on /12/ introduced 27 October 2022 with deprecation and end of life both TBD, and version 8 on /8/ end of life 31 August 2021 (accessed 14 November 2026)
- X developer docs, Ads API 'Rate limiting': 450 writes per minute as a shared category, 10,000 core entity reads and 2,000 other account reads per 15 minutes, 5 global reads per 15 minutes, and the statement that there is no programmatic index of per-endpoint limits (accessed 14 November 2026)
Product designer and indie hacker. Runs the agent on his own X account every day and writes up what the data shows, including when it's inconvenient.
Follow on X →