[cathalging]

Why?

The Help Center, Articles, Collections and Help Center Redirects reference had drifted from what the API actually sends and accepts. It had wrong URLs, missing error responses and parameters, fields the API ignores, and stale examples. Developers following it wrote requests that failed or read fields that never arrive.

How?

These changes correct the 2.17 and Preview references in place, checked against the API's behaviour. They document each operation's OAuth scope, the real errors and limits, and examples that match current responses.

Risks

Some generated Preview SDK types change at the next SDK release. Request fields the API ignores are removed, search state becomes an enum, and title, author_id and collection name become optional.

_{Generated with Claude Code}

[yasser-aboelgheit-intercom]

Thanks Cathal, this is a thorough pass. I checked the changed claims against the API's behaviour and found nothing wrong: the scopes, the error codes and messages, the per_page limits, the search state values and default, the 500-character phrase limit, the home/null parent handling, the scheduling rules and the new response fields all match. Both specs parse with no dangling refs, operationIds are unchanged, and fern check shows 0 errors and the same 317 warnings as main.

A few questions:

1. 2.17 contract changes. The 2.17 copy isn't only descriptions. parent_type is removed from the create and update article requests, required is dropped from create article (title, author_id) and create collection (name), and search state becomes an enum. None of this changes the wire behaviour, but 2.17 is released. Is it worth a changelog line, or keeping these shape edits to Preview only?

2. Empty search results. The description now says data is [] when nothing matches, but article_search_response.data is still typed as an object. Generated Preview SDKs would then fail to parse an empty search. I see this was left out on purpose. Is there a follow-up for a oneOf (or an SDK override)?

3. Stage draft "ignored" fields. The fields not applied by PUT /articles/{id}/draft are still validated, so a malformed audience_ids still returns 422 and a malformed url_redirects still returns 400. Would "not applied, though still validated" be more accurate than "ignored"?

4. Update collection help_center_id. It's described as "the Help Center the collection belongs to", but it's only checked, never applied, so it can't move a collection. The consistency check also looks at the collection's children, so an empty collection gets "Supplied help center id doesn't match the collection's help center id." even when the id is correct. Should the description say it's a check only?

5. Publish draft author_id. It's right that this is only used when the token has no teammate, but in that case it's required: leaving it out returns 400 parameter_not_found. Should the description say so, given the schema also says the body can be omitted?

6. Create article title/author_id. "Required unless given in translated_content under the default Help Center locale" holds when the article's locale is the default. If locale (or the parent collection) gives a different locale, values given only under the default locale pass validation but aren't used, and the create returns 404 for the author. Is that edge case worth a clause?

7. Small one. On create article translated_content, the new description next to a $ref is ignored under OpenAPI 3.0.1 unless it's wrapped in allOf.

Approving. None of these block, but I'd like an answer on 1.

~ Automated via Claude

[yasser-aboelgheit-intercom]

Thanks Cathal. The follow-up wording on the staged draft, publish author_id and collection help_center_id reads well, and nullable on update parent_id matches how null is handled. Re-checked the new head: both specs parse with no dangling refs, and fern check shows 0 errors and the same 317 warnings as main. My earlier question about a changelog line for the 2.17 shape changes still stands, but it doesn't block.

~ Automated via Claude