[markdennis22]

Why?

The 2.17 spec for the companies endpoints didn't match the API. company.notes had a shape the API never sends, the lists described cursor paging where the API pages by number, 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 companies endpoints and company 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?
Company.notes becomes a list object (type, data, url, total_count, has_more) instead of a notes array	Yes, if it reads notes.notes	No. The API sends the list object
CompanyNote loses created_at, company and author, gains url, and the CompanyNoteCompany type is removed	Yes, if it reads those fields	No. Notes embedded in a company never carry them
CompanyList.pages becomes PagesLink instead of CursorPages	Yes, if it reads pages.next as an object	No. The API sends a URL
CompanyScroll.pages is no longer CursorPages and is always null	Yes, if it reads pages	No. The API always sends null
Search companies returns a new CompanySearchResponse instead of CompanyList	Possibly, because the return type is renamed	Yes. The response itself is unchanged
Retrieve a company by ID returns Company or a new CompanyUserList instead of only Company	Yes, if it reads the result as a Company without narrowing	Yes. A company is still returned unless type is user or users
Retrieve companies gains CompanyUserList as a third response shape	Possibly, if it matches on every shape	Yes. A company or company list is still returned unless type is user or users and company_id or name is set
List companies order becomes an asc/desc enum, and both retrieve operations gain a type enum	Unlikely	Other order values were already rejected
New optional id on the create request and query parameters on list attached contacts	No	—

Notes for reviewers

• fern check shows 0 errors and the same 317 warnings as main. There are no new dangling refs, and the operations are unchanged.
• In Preview, notes in the company examples and update_last_request_at in the update request were already there, so they keep their place and take the 2.17 values.

_{Generated with Claude Code}

[cathalging]

Approving. One existing sentence is worth fixing here or in a follow-up, your call: the companies scroll warning (2.17 L9034, Preview L7794). When the scroll fails on a network error, the API returns a generic 500 server_error rather than the quoted message. The open scroll also isn't cleared, so starting a new one within a minute returns 400 scroll_exists. Suggest saying the request returns a 500, and to wait up to a minute before starting a new scroll.

~ Automated via Claude (about: https://github.com/intercom/claude-plugins/blob/main/plugins/base/docs/external-message-attribution.md)