Add Fin Agent API to OpenAPI specs and Postman

[rahulgdsouza]

Why?

The Fin Agent API (POST /fin/start, POST /fin/reply) was introduced in v2.14 and is fully documented in developer-docs, but was completely missing from the OpenAPI specs in this repo. Since Postman collections are generated from these specs, they were also missing the Fin Agent endpoints. Separately, the v2.15 Postman collection was never generated (the bulk update in PR #302 covered v2.7-2.14 only).

How?

Copied the exact Fin Agent API definitions (2 paths, 8 schemas, 1 tag) from the developer-docs YAML specs into v2.14, v2.15, and Preview specs — programmatically verified to match developer-docs exactly. Ran the Postman generation script to create the missing v2.15 collection and refresh v2.14/Preview with the new endpoints. Fern SDK overrides were intentionally skipped (can be added before the next SDK release if custom method naming is desired).

Closes https://github.com/intercom/intercom/issues/489015

Implementation Plan

Plan: Add Fin Agent API to OpenAPI specs + Generate v2.15 Postman Collection

Context

The Fin Agent API (POST /fin/start, POST /fin/reply) was introduced in v2.14 and is fully documented in developer-docs (YAML specs + markdown guides), but is completely missing from the Intercom-OpenAPI repo. Since Postman collections are auto-generated from this repo's specs, they're also missing the Fin Agent endpoints.

Separately, the v2.15 Postman collection was never generated — the bulk Postman update (PR #302) covered v2.7-2.14 and Unstable/Preview, but v2.15 was skipped because the CI pipeline only processes changed YAML files and v2.15 was never touched after the pipeline was set up.

This plan addresses both gaps in a single PR.

What needs to be added

Paths (2 endpoints)

• POST /fin/start — Initialize a conversation with Fin
• POST /fin/reply — Send a user reply back to Fin

Schemas (8 component schemas)

• fin_agent_message — Message object (author, body, timestamp)
• fin_agent_user — User object (id, name, email, attributes)
• fin_agent_attachment — File or URL attachment
• fin_agent_conversation_metadata — History + conversation attributes
• fin_agent_attribute_errors — Error details for invalid attributes
• fin_agent_status_updated_event — Webhook/SSE status change event
• fin_agent_replied_event — Webhook/SSE reply event
• fin_agent_reply_chunk_event — SSE streaming chunk event

Tag (1 new tag)

• Fin Agent — Tag definition with description

Versions affected

• descriptions/2.14/api.intercom.io.yaml — First version with Fin Agent API; drives SDK generation via Fern
• descriptions/2.15/api.intercom.io.yaml — Same Fin Agent content as v2.14
• descriptions/0/api.intercom.io.yaml — Preview; has enhancements (replying status in events)

Version differences (Preview vs stable)

Component	v2.14 / v2.15	Preview
fin_agent_status_updated_event status enum	escalated, resolved, complete	+ awaiting_user_reply
fin_agent_replied_event status enum	awaiting_user_reply	replying, awaiting_user_reply
fin_agent_reply_chunk_event status enum	awaiting_user_reply	replying

Implementation Steps

Step 1: Add Fin Agent API to v2.14 spec

File: descriptions/2.14/api.intercom.io.yaml

1. Add 8 schemas to components/schemas in alphabetical position
2. Add 2 path definitions (/fin/start, /fin/reply) to the paths section
3. Add Fin Agent tag to the tags array

Step 2: Add Fin Agent API to v2.15 spec

Identical content to v2.14 — same paths, schemas, and tag.

Step 3: Add Fin Agent API to Preview spec

Same structure but with Preview-specific differences in the three event schemas.

Step 4-5: Fern SDK overrides (skipped)

Skipped — Fern will auto-generate SDK method names from operationId. Can be added later.

Step 6: Generate Postman collections

Run node scripts/postman/generate-postman-in-repo.js to generate all Postman collections.

Step 7: Validate

• Parse all 3 YAML files with Node.js YAML parser to catch syntax errors
• Programmatically verify all paths, schemas, and tags match developer-docs exactly
• Verify Postman collections contain Fin Agent endpoints

_{Generated with Claude Code}