Add descriptions/2.17 spec

[geetikabagga]

Why?

API version 2.17 ships today, and this repo has no 2.17 spec yet, so SDKs and docs can't describe it.

How?

Adds a 2.17 spec as a copy of the current 2.16, with the endpoints and fields that graduate in 2.17 copied from Preview and their Preview-only wording made stable. It also fixes three schema errors in both 2.17 and Preview: the missing ms_teams_data_cannot_be_merged merge preview reason code, the deleted folder id type, and GET /folders paging.

Notes for reviewers

• The data connector versions endpoints are included, but are not in the marker on line 1, because they are tracked outside the main version list.
• Behavioural changes in 2.17 have no spec surface, so they are documented only in the 2.17 changelog on the developer docs site.
• A few Preview descriptions are copied as they are, though they are slightly off: the scorecard note author null case and call_summary call_id presence.

_{Generated with Claude Code}

[markdennis22]

Reviewed at 9ac856e. One blocking item, then three cheap fixes.

Blocking — 2.17 was copied from a 2.16 that main has since moved past

Two commits landed on main after this branch was created (10:58 UTC today), both changing descriptions/2.16/api.intercom.io.yaml:

• Add channel field to ticket creation endpoints (from v2.14) #320 — Add channel field to ticket creation endpoints (from v2.14) — merged 12:40 UTC
• Align the 2.16 API reference across repositories #714 — Align the 2.16 API reference across repositories — merged 13:33 UTC

Because the convention here is add-only, merging this PR keeps main's newer 2.16 and Preview and adds a 2.17 copied from the older 2.16. The result on main would be 2.16 and Preview documenting fields that 2.17 — the version sitting between them — does not.

Diffing descriptions/2.17 at this head against descriptions/2.16 on main (43 changed lines), 2.17 is missing:

Missing from the new 2.17	Added to 2.16 by
ticket.channel and create_ticket_request.channel, plus the channel key in the POST /tickets, POST /tickets/enqueue and GET /tickets/{ticket_id} examples	#320
ai_call_response.data	#714
the inbox_bulk_action enum value (two places)	#714
the corrected previous_state / new_state descriptions on the admin occupancy activity log (the IP-allowlist wording)	#714
the SSE "available by application only" admonition	#714

channel is the one consumers will feel: it is documented in both 2.16 and Preview on main, so anyone pinned to 2.17 would see no way to set a ticket's channel at creation and no channel on the response, while the API still accepts and returns it.

Fix: merge main, re-copy 2.16 → 2.17, then re-apply the 2.17 graduation edits.

Same cause, worth knowing: #714 brought the two repos' 2.16 copies from 89 to 30 differing lines. The 2.17 copies here and in developer-docs#1224 differ by 103 lines, because each repo's 2.17 inherited its own pre-alignment 2.16 — this one carries the occupancy properties and the admin_occupancy_* enum values, that one carries inbox_bulk_action and the ai_call_response 200. So 2.17 currently ships with more cross-repo drift than the 2.16 you just aligned. A rebase on both sides recovers most of it.

Worth fixing before 2.17 is live

All three are inherited from Preview rather than introduced here, and all three are one-line fixes — much cheaper now than against a released version:

1. merge_preview_reason.code lists 9 codes; Api::V3::Contacts::Presenters::MergePreviewResponse::REASON_MESSAGES on master defines 13. The one worth adding is ms_teams_data_cannot_be_merged — it is the same kind of reassignment blocker as whatsapp_data_cannot_be_merged, telegram_data_cannot_be_merged and phone_data_cannot_be_merged, all three of which are documented, and it has a producer at app/services/user_service/merge_contacts/steps/reassign/ms_teams_data.rb. The other three absent codes (source_is_user, user_to_lead, source_has_telegram_data) are user-to-user merge concerns and are correctly out of scope for 2.17. I did not trace the preview path end to end, so treat reachability as likely rather than proven.
2. deleted_folder_object.id is typed integer with example 6, but Api::V3::FoldersController#destroy renders { id: params[:id], object: "folder", deleted: true } — the id comes back as a string.
3. GET /folders points pages at cursor_pages, which carries next → starting_after_paging, and gives per_page a maximum of 150. Api::V3::Folder::Presenters::FolderListResponse#pages returns only type/page/per_page/total_pages, and Folder::Service#get_all_folders is Kaminari page-based with no cap (it defaults per_page to 50). A client written against this waits for a next cursor that never arrives. It is also the only path in the whole spec that references cursor_pages.

Checked and clean

182 paths, 258 operations and 379 schemas, identical to the set in developer-docs#1224; nothing removed at path, operation or schema level relative to this branch's own base; the 23 new operations and 40 new schemas match the graduated change list, including DELETE /notes/{note_id}. Valid YAML, no duplicate mapping keys, no dangling $refs (368 resolved), unreferenced-schema set unchanged from 2.16. info.version and the intercom_version enum, default and example are all 2.17. Preview is untouched. QA scorecards are handled correctly — 2.17 keeps scorecard_version_id and reason_ids while adding the five graduated scorecard fields — and non-graduated Preview content is properly excluded (whatsapp_number, formatted_phone, companies bulk, roles and auth tokens, platform handoff, part-type filtering).

Note that fern check only validates the 2.14 and Preview groups, so nothing in CI has looked at this file.

~ Automated via Claude

[markdennis22]

Approving. Re-reviewed at 65b1224 (was 9ac856e), with every baseline pinned and blob-verified against main as it stands now.

Prior finding	Verdict
2.17 copied from a stale 2.16 — missing ticket.channel, create_ticket_request.channel + 3 examples, ai_call_response.data, inbox_bulk_action enum (×2), two description corrections, SSE admonition	Resolved
merge_preview_reason.code missing ms_teams_data_cannot_be_merged	Resolved
deleted_folder_object.id typed integer	Resolved
GET /folders documented with a cursor next and per_page maximum: 150	Resolved
103 lines of cross-repo drift in the new 2.17 copies	Resolved as far as this PR can — now 42, of which 30 is 2.16's own pre-existing drift

The rebuild is clean against the current 2.16: zero schemas lost, zero property regressions across all 379 schemas, zero operations lost, zero enum values lost, and the 23 new operations / 40 new schemas are unchanged. ticket.channel and create_ticket_request.channel are back with both request examples. info.version, and intercom_version's enum, default and example, are all 2.17. No dangling $refs, no duplicate mapping keys. Fern Check is green.

Fixing the three schema errors in Preview as well as 2.17 was the right call — those were Preview-inherited, so patching only 2.17 would have regenerated them into 2.18. The Preview diff is 11 lines, all additive or corrective, with nothing pruned: maximum: 150 removed, cursor_pages → pages_link on /folders, the deleted-folder id retyped, and ms_teams_data_cannot_be_merged added to both the enum and the reason-code table in the description. Adding the glossary row alongside the enum value is the bit that usually gets missed.

A correction to my earlier comment. I wrote that /folders was "the only path in the whole spec that references cursor_pages". That was wrong — it was the only path referencing it inline; 25 operations reach it through their named list-response schemas, which my walker didn't follow. It doesn't change the finding or the fix: pages_link is shared with 5 sibling endpoints including GET /ai/external_pages and GET /ai/content_import_sources, so /folders now matches its neighbours rather than standing alone.

One residual, not for this PR: the only remaining property-level difference between this 2.17 and developer-docs#1224's is ai_call_response.attributes, which developer-docs documents and this repo does not — and that gap exists at 2.16 on main too, so it predates the cut. Worth picking up in the next alignment pass rather than here. The rest of the 42 lines is wording ("UNIX" vs "Unix" timestamp ×6, two channel description variants) and one example's position.

~ Automated via Claude