[cathalging]

Why?

The Fin Agent API, AI Content, data connector and workflow export operations describe errors, fields and behaviour the API doesn't have, so clients and generated SDKs are built against the wrong contract.

How?

Each changed claim was checked against what the API actually returns and corrected in both 2.17 and Preview.

Notes for reviewers: shape changes in 2.17 and the Preview SDK

Each of these matches what the API returns today, but changes the documented contract or a generated SDK type:

• Fin Agent API validation errors: 400 error.list becomes 422 {errors: {...}}.
• Capabilities items: type and id are removed, name is now the tool name, description is nullable, and inputSchema, endpoint and method are added.
• Run procedure: message becomes its own type with only body required, in place of the shared Fin Agent message type.
• External pages: locale is no longer limited to en. Update now requires external_id instead of url, and replaces fin_availability with the ai_agent_availability, ai_copilot_availability and ai_sales_agent_availability flags.
• Data connectors: headers items require name and value, data_inputs items require name, description, type and required, and execution_type, configuration_response_type and data_transformation_type are no longer nullable.
• Workflow export: the 403 is removed; 401 and 503 are added.

_{Generated with Claude Code}

[yasser-aboelgheit-intercom]

Thanks for this. It's a big one, and most of it holds up. I checked it with the spec comparator, ref checks, fern check (0 errors, no new warnings) and the Preview Fern IR, and checked each claim against how the API behaves. The "escalation closes the original conversation" claim is confirmed.

A few questions:

1. internal_description auto-sync — The create and update data connector requests say that if internal_description is omitted while description is sent, it's set to description. Through the API that never happens. An omitted internal_description keeps its stored value on update, and starts as "" on create. Should the sentence go, and the create 201 example stop showing internal_description equal to description?
2. environment "Fin for Platforms workspaces with environments" — The API only checks whether the workspace is Fin for Platforms. On a Fin for Platforms workspace with no environments, an identifier returns 422 "Invalid environment" rather than being ignored. Could this drop "with environments"?
3. Escalate capability text — The /fin/capabilities example's escalate description says "...leaving this one untouched...". That's what the API returns today, but it contradicts the escalate docs, which say the original is closed. Should the example carry a note until the returned text is updated?
4. 403 "Response format not available" — Every Fin Agent API operation returns this when response_format: markdown isn't available, not just start, reply and ask. Should run_procedure, capabilities, escalate and csat list it too?
5. Content import source url — A URL whose host isn't a public domain seems to pass the format check and then fail with 500 server_error rather than 400. Can you confirm? If so, should the docs avoid promising a 400 for that case until the API returns one?
6. Breaking shape changes — These change 2.17 and the Preview SDK. The capabilities items lose type and id, name changes meaning, description becomes nullable and inputSchema is added. Elsewhere, fin_availability is removed from the update external page request, external_id becomes required, several data connector fields lose nullable, and workflow export's 403 becomes 503. Each one matches the API, but could the PR body list them, and could someone who owns the public contract sign off?
7. Merge conflicts — This conflicts with main (the Help Center PR, #744) and with #752 in the 2.17 spec. It needs a rebase.

Holding approval for items 1, 2 and 6, and the rebase.

~ Automated via Claude

[markdennis22]

Superseded by the review below.

[cathalging]

Thanks Mark. Fixed in f561138:

1. internal_description: the auto-sync sentence is gone. Create now says "If omitted, it is an empty string" and the 201 example shows internal_description: ''. Update says it keeps its current value; a later pass added the one exception (a connector with no internal description yet gets description copied in).
2. environment: "with environments" is dropped. It now reads "Only Fin for Platforms workspaces use it; other workspaces ignore it."
3. Transform return: transform_code_block.code now ends "The code must return the transformed value." in both 2.17 and Preview.
4. Markdown replies: fin_agent_replied_event has a new message.format (html/markdown, present only when the request set response_format: markdown), and body now says it follows format.
5. page: now says page can't exceed 5,001 and page × per_page can't exceed 10,000, with the 400 for each and an example for the scroll-API one.
6. Capabilities: I've left the example verbatim, since it's what the API returns today. Fixing the returned escalate text and the reply/ask inputSchema timestamp rule is a change on the API side, and I've logged it as a follow-up. A note on the example would go stale once that lands.
7. The shape changes are now listed in the PR body. On sign-off: I'm not sure who owns the public contract here. Does your approval cover it, or is there someone you'd want to sign off as well?

A further pass against the API turned up a few more, fixed in 7cea9ee:

• the start/reply/ask/run-procedure status is always thinking;
• an escalation workflow's first steps run before the original conversation is closed again;
• escalating a user returns a temporary conversation, not the teammate's;
• omitting url on an external page update clears it;
• Preview's external page 404s now match 2.17;
• per_page has minimum: 1;
• plus smaller data connector and procedure-name wording fixes.

~ Automated via Claude

[markdennis22]

Thanks Cathal. The shape changes are signed off: they correct the reference to what the API already returns. Three things left before I approve:

1. Update internal_description: the copy from description only happens when the stored value is null. Connectors created through the API store "", so they never get it. Please say the exception only applies to a null value.
2. user escalation: the separate Helpdesk conversation only opens when no escalation workflow matches. Please add "by default" in the escalate description and the intercom_conversation_id description.
3. Capabilities example: please add a line to the PR body notes saying the example's escalate text is kept as the API returns it, even though it contradicts the escalate description, until that text is updated.

~ Automated via Claude

[markdennis22]

Approving. The three points in my review above still stand, so please pick them up before merging.

~ Automated via Claude