Publish POST /fin/escalate in the Preview spec and clarify /fin/ask escalation wording

[rahulgdsouza]

Why?

POST /fin/escalate is a published Preview endpoint — it's documented on developers.intercom.com and is one of the six Fin Agent API orchestration endpoints — but it was missing from this spec entirely. The other five (/fin/capabilities, /fin/ask, /fin/reply, /fin/procedures/{procedure_id}/run, /fin/start) are all here, so this looks like an oversight rather than a deliberate exclusion.

Consequence: no generated escalate method in any of the four SDKs (TS, Java, Python, PHP), and no Postman entry.

Separately, the askFin description said Fin "will not escalate to a human", which reads as absolute. Fin does not escalate an /fin/ask conversation on its own, but such a conversation can be handed off with /fin/escalate — a clarification that only makes sense once the endpoint it points at is actually defined here.

What changed?

descriptions/0 only:

• Added POST /fin/escalate (escalateFinConversation) — ported verbatim from the @Preview spec in developer-docs, inserted in the same position in the Fin Agent group (after /fin/procedures/{procedure_id}/run, before /fin/start).
• askFin description — "will not escalate to a human" → "will not escalate to a human on its own", plus a note that an ask conversation can be handed off with POST /fin/escalate.
• Fin Agent tag description — added the /fin/escalate clause to the endpoint list.

What the escalate operation documents

• Either conversation_id (escalate an existing agent conversation, including one started with /fin/ask) or user (escalate with no prior conversation).
• Intercom Helpdesk default: Fin summarises and opens a new Helpdesk conversation carrying the summary as an internal note; the original agent conversation is not reassigned. An escalation Operator Workflow overrides this.
• On Fin for Platforms there is no Intercom inbox, so an escalation no workflow handles does not open a Helpdesk conversation for a teammate — either path.
• Escalating an existing conversation sets its AI Agent resolution state to escalated, readable as ai_agent.resolution_state on the Conversations API.
• Responses: 200, 400, 401. Only pre-existing schemas are referenced (error, fin_agent_user, intercom_version) — no new components.

Verification

• Spec parses; path count 180 → 181; escalateFinConversation resolves under the Fin Agent tag.
• Every $ref in the document resolves — checked doc-wide, not just in the new block.
• The ported operation is structurally identical to the developer-docs @Preview version (deep-equal on the parsed object).
• fern check was not run locally (fern isn't installed) — relying on the fern_check CI job.

Sync note

Pairs with intercom/developer-docs#1066, which carries the same wording plus the guide changes. developer-docs is the source of truth for the spec YAML and the two repos are kept in step by manual copy, which is how this endpoint came to be missing on this side.

_{Generated with Claude Code}

[shrek-intercom]

✅ PR Review Summary: APPROVE

	Summary
✅	🎯 Problem — The PR clearly and concisely explains the problem (misleading absolute wording), the rationale (handoffs are still possible), and the minimal fix being applied.
✅	📝 Alignment — The PR description accurately and completely reflects the code change, correctly identifying the exact rewording, the affected file, and the documentation-only nature of the modification.
ℹ️	🧠 Correctness — Disabled for this repository.
✅	🦺 Safety — The change is a single, minimal wording update to a description string in the Unstable/Preview spec, with no schema, endpoint, or operational changes and no impact on released versions.
✅	🚦 Auto-approval — Within size limit (0/150 LOC).

Per-criterion details

Problem

Excellent concise PR that clearly explains the problem (misleading absolute wording that implies no handoff is possible), why it matters (conversations can still be handed off to humans), and the minimal change being made. No fluff, just the essential context a reviewer needs.

Alignment

The PR description states:

1. The change rewords "will not escalate to a human" to "will not escalate to a human on its own." — This matches the diff exactly.
2. It says the change is description text only with no schema or operation changes — The diff confirms only a description string in the YAML was modified.
3. It says the file changed is descriptions/0/api.intercom.io.yaml — This matches.
4. The rationale about clarifying that Fin doesn't escalate on its own but the conversation can still be handed off is consistent with the wording change.

The description accurately and completely reflects what the code change does.

Safety

This PR makes a single, minimal text clarification in the Unstable/Preview spec (descriptions/0/api.intercom.io.yaml). It adds three words ("on its own") to a description string for the /fin/ask endpoint. There are no schema, endpoint, field, type, or operational changes — purely a wording improvement to documentation text. The change is confined entirely to the Unstable/Preview tier, touches no released versions, no Fern config, no scripts, no CI/CD files, and introduces no breaking changes.

<violated_criteria>
</violated_criteria>

_{Rate this comment 👍 / 👎 to help us improve 🙏 · Disagree with assessment? Establish ground truth here}

[Magrath]

Suggested change

	On Fin for Platforms there is no Intercom inbox, so an escalation that no workflow
	On Fin for Platforms, there is no Intercom inbox, so an escalation that no workflow

[rahulgdsouza]

I'll tackle this with the CSAT changes.