fix(openapi): post expansions omit the documented referenced_tweets.id value #499

Summary

The published OpenAPI post-expansion enum excludes referenced_tweets.id, although the expansions guide documents it for retrieving referenced posts. Instead, the enum lists referenced_posts. A client validating a post lookup against this enum rejects the guide's parameter value before sending the request. This report concerns the documentation/spec disagreement; it does not assert whether the API accepts referenced_posts.

Runtime or environment

The documentation source baseline is main commit 5fcfe3da51461ef1c0b59a028da9c365547cad4c. The repository has no published releases. The checked-in OpenAPI specification and the document freshly fetched from https://docs.x.com/openapi.json parse to identical JSON and identify their version as 2.172. A separately supplied observation used xurl 1.3.4; that observation was not rerun during this investigation.

Steps to reproduce

1. Fetch the published specification and inspect components.parameters.PostExpansionsParameter.schema.items.enum.
2. Follow the expansions parameter reference on paths["/2/tweets/{id}"].get.parameters to that component.
3. Compare the allowed values with the post-expansions table in https://docs.x.com/x-api/fundamentals/expansions and the generated lookup reference at https://docs.x.com/x-api/posts/get-post-by-id.
4. Check whether the enum contains referenced_tweets.id. It does not; it contains referenced_posts.

These documentation checks were executed. No live X API request was made. The supplied live observation reports that xurl --auth app read <post-id> returned data and includes.tweets with a request using expansions=referenced_tweets.id; the private post identifier and response are deliberately omitted, and the live behavior has not been independently reproduced here.

Expected behavior

The post lookup's published expansion enum and expansions guide should agree on the supported request value for retrieving referenced posts. A request value documented by the guide should not be excluded by the schema used to describe the same endpoint.

Actual behavior

The enum allows referenced_posts and omits referenced_tweets.id, while the guide lists the latter. The generated lookup reference reproduces the enum, so the disagreement is visible on the published site as well as in the source. The OpenAPI document does contain referenced_tweets.id in other endpoint-specific parameter enums; the omission reported here is specifically in PostExpansionsParameter.

Evidence

• Expected source: The source guide's post-expansions table lists referenced_tweets.id as returning referenced post objects, at x-api/fundamentals/expansions.mdx, lines 45–50.
• Failure source: components.parameters.PostExpansionsParameter has the contrary enum at openapi.json, lines 39108–39137; the fetched spec and generated reference preserve it.
• Evidence provenance: observed

The current source, published spec, and published Markdown were inspected directly. The live API result described above is supplied evidence only.

• Local verification: reproduced
• Reproduction completeness: complete

Restoration check

Fetch the published spec and lookup reference again and compare the post-expansion enum with the guide. They should consistently describe the supported parameter value. Confirm the resolved enum through the lookup operation's parameter reference rather than searching for the string elsewhere in the document. This check establishes documentation consistency; verifying server acceptance of either spelling requires a separate authorized API check.

Triage assessment

• Impact level: P2
• Assessment status: supported
• Impact basis: The schema excludes a documented post-lookup request value, making schema validation reject that value and leaving spec-driven clients without the documented referenced-post expansion.
• Workaround status: available
• Workaround basis: The published guide provides the alternative spelling, which can be supplied directly by a client without enforcing the inconsistent enum. The supplied observation reports successful use of that spelling; no server-side claim about the other spelling is made.