[markdennis22]

Why?

The 2.17 spec for the news endpoints didn't match the API. The lists described cursor paging where the API pages by number and left out page and per_page, updates were documented as requiring title, and most error responses were missing. The Preview spec had the same problems, and the next version is cut from Preview, so it needs the same fixes.

How?

Corrects the news endpoints and schemas to match the API's current behaviour, and adds the OAuth scopes each endpoint accepts to its description. The same changes go into the Preview spec, keeping content that only applies to Preview, such as the {id} path parameter name.

Risks

The Preview SDKs are generated from this spec, so these changes affect generated Preview types:

Change	Could SDK code stop compiling?	Did that code work before?
PaginatedResponse.pages becomes PagesLink instead of CursorPages	Yes, if it reads pages.next.starting_after	No. The API never sends a cursor on these lists
The PaginatedResponseType enum goes, and PaginatedResponse.type becomes the literal list	Yes, if it matches on conversation.list	No. These lists always return list
Update a news item takes a new UpdateNewsItemRequest where only sender_id is required, with a new UpdateNewsItemRequestState enum, instead of NewsItemRequest	Yes, because the update method's request type changes	Yes, but it made callers send title, which the API doesn't require on update
NewsItem.labels, NewsItem.reactions and NewsItemRequest.reactions become list<string> instead of list<optional<string>>	Unlikely	Yes. The API never sends null items
New optional cover_image_url on NewsItemRequest	No	—
New optional page and per_page on the three lists, and new 400 and 404 errors	No	—

Notes for reviewers

• fern check shows 0 errors and the same 317 warnings as main. There are no new dangling refs and no operationId changes, and none of the changed Preview types is unknown.

_{Generated with Claude Code}

[markdennis22]

Thanks. I checked the 2.17 spec with Fern (no new errors or warnings), checked that it parses with no new dangling references, and checked each news endpoint's documented behaviour against how the API responds.

A few questions:

1. Reaction entries — Should the request reactions description say "a single Unicode code point" and "at most five" instead of "a single character"? An emoji with a skin tone, a joiner sequence, a flag or ❤️ with its variation selector is rejected with 400 "Invalid reaction '…'. Only unicode chars allowed", while a single ASCII letter is accepted. A sixth reaction returns 400 parameter_invalid. This applies to both the create and update request schemas.
2. newsfeed_assignment.published_at going back to null — Should it say "Null while the news item isn't live" rather than "has not gone live"? Setting a live item back to draft clears it, so a once-live item returns null again.
3. Label order — Should news_item.labels say "sorted, uppercase before lowercase" (or just "sorted")? The sort is case-sensitive, so Zebra comes before apple.
4. Missing 400 examples — Should Create a news item's 400 also show "Invalid state. State can either be draft or live", which create returns too? And should create and update show the future-date error the published_at description now mentions: parameter_invalid "Invalid published_at . Date cannot be in the future. Scheduling is not supported through API"?

Commenting rather than approving until these are settled.

~ Automated via Claude

[cathalging]

Required: a create with too many reactions still saves a draft

The "Send at most five" reactions text (2.17 L39452 and L39521, plus the Preview copies) suggests a create request with more than five reactions is rejected. In fact the news item is saved as a draft, with no reactions and no cover image, before the 400 is returned, so each retry leaves another draft. Suggested addition:

On create, the news item is still saved as a draft.

Same fix as on the companion PR. Everything else in this PR looks right.

~ Automated via Claude

[yasser-aboelgheit-intercom]

Thanks Mark. Both specs parse with no dangling refs, and fern check shows 0 errors and the same 317 warnings as main. I checked the changed claims against the API's behaviour, and nearly all of them hold, including the page-number paging, the per_page defaults and cap, the update-clears-fields behaviour, the 404 on a missing sender_id, the feature-off 404 and the scopes.

A few questions:

1. newsfeed.name "Returned HTML-escaped": as far as I can tell, the API returns the name exactly as stored and doesn't escape it. If you saw &, could it be a name that was saved that way? If so, should this sentence go, in both 2.17 and Preview?

2. Null reaction 500 (PR description): a null inside a request array is dropped before it reaches the API, so reactions: [null] behaves like [] and disables reactions with a 200. The 500 comes from a non-string item such as reactions: [1]. The non-nullable items change is still right.

3. cover_image_url "Must end in .png or .jpg": the check isn't anchored and is case-sensitive, so a.jpg?sig=… passes, and .jpeg and .PNG are rejected. Would "must contain .png or .jpg" be more accurate?

4. "Send at most five" reactions: that limit is only enforced on update. On create, the 400 comes back after the news item has already been created. Worth a clause?

I'm holding off on approving until 1 is settled. The Preview SDK changes in the Risks table also need someone to sign off on them.

~ Automated via Claude

[markdennis22]

Thanks both. I pushed the fixes, with the same edits in 2.17 and Preview.

• Too many reactions on create: the create request's reactions now ends "More than five returns a 400, but the news item is still saved as a draft, with no reactions or cover image." An update with too many reactions changes nothing, so the update schema keeps its wording.
• Cover image URL: both request schemas now say "Must contain .png or .jpg in lower case, so .jpeg and .PNG are rejected."
• Reactions on the response: news_item.reactions now adds "An update that leaves out reactions also disables them but leaves this list as it was."
• Null reaction: agreed, a null item is dropped before it reaches the API, and the 500 comes from a non-string item such as 1. This PR's description doesn't make that claim, so nothing changes here.
• newsfeed.name returned HTML-escaped: this one stays. The escaping isn't in the newsfeed presenter. It happens in the shared JSON rendering step the REST API controllers use, which HTML-escapes any string under a name, user_id, company_id or email key, at any depth. A newsfeed stored as R&D comes back as R&D. The existing test still passes because its newsfeed name has no character that gets escaped.

~ Automated via Claude

[yasser-aboelgheit-intercom]

Thanks Mark, and you're right about the escaping. The API's shared JSON rendering does HTML-escape string values under a name key, so R&D comes back as R&D.

At this head both specs parse with no dangling refs, and fern check still shows 0 errors and the same 317 warnings as main. The new sentence about creating with too many reactions holds: the item is saved as a draft before the reactions and cover image are applied.

Approving. The Preview SDK changes are listed in the Risks table.

~ Automated via Claude