Deprecate parent_id and parent_type from article API responses (Preview)

[ib-skoric]

Why?

The parent_id and parent_type fields on article responses are derived from a denormalized column that is frequently out of sync (~835K affected articles). The parent_ids field (introduced in v2.10) already returns correct data and supersedes them. The OpenAPI Preview spec must reflect their removal.

How?

Remove parent_id and parent_type from the article_list_item response schema and from all five inline article response examples in descriptions/0/api.intercom.io.yaml. Stable version specs (2.7–2.15) are left unchanged.

Decisions

• Preview spec only: The upstream change is registered as define_is_ready_for_release false (Unstable), so only the Preview spec is updated; stable specs retain the fields for backwards compatibility.
• Response schema only: parent_id/parent_type are kept in request schemas (create_article_request, update_article_request) and request examples because the monolith PR only changes the response presenter, not input handling.
• Collection fields untouched: parent_id/parent_type on collection schemas and collection endpoint examples represent a separate hierarchy concept and are not affected by this change.

Review Guidance

Dimension	Score	Reasoning
Complexity	█░░░░░░░░░ 1.2	Why Single-file YAML edit with surgical line removals; no cross-cutting concerns.
Unintuitiveness	███░░░░░░░ 3.1	Why The Order description describes adding a locale parameter, which is the opposite of what the diff does — removal of two fields — though the plan and PR description both correct this explicitly.
Risk Surface	█░░░░░░░░░ 1.8	Why Preview spec only; stable specs untouched, and request schemas are correctly left alone — low risk for existing consumers.

Attention: Normal review — The diff itself is clean and straightforward.

_{🧪 This AI-generated review guidance is experimental. Share feedback}

Implementation Plan

Worker Implementation Plan

Plan: Deprecate parent_id and parent_type from Article API Responses (Preview Spec)

Context

PR intercom/intercom#491162 removes parent_id and parent_type from article response payloads. These fields are derived from a denormalized article_group_id column that is frequently out of sync (835K affected articles). The parent_ids field (added in v2.10) already returns correct data by reading from GroupMembership directly.

The change is registered in the Unstable version with define_is_ready_for_release false. For this OpenAPI spec update, we apply the change to the Preview spec (descriptions/0/api.intercom.io.yaml) only. Stable versions (2.7–2.15) remain unchanged.

Note: The order description incorrectly states this is about a locale parameter. The actual PR deprecates parent_id/parent_type from article responses.

Target File

descriptions/0/api.intercom.io.yaml — the Preview spec (~28K lines)

Changes

1. Remove parent_id and parent_type from article_list_item schema (response schema)

File: descriptions/0/api.intercom.io.yaml
Lines: 19027–19046

Remove these two property blocks from the article_list_item schema:

        parent_id:
          type: integer
          nullable: true
          description: The id of the article's parent collection or section. An article
            without this field stands alone.
          example: '125685'

        parent_type:
          type: string
          nullable: true
          description: The type of parent, which can either be a `collection` or `section`.
          example: collection

Keep parent_ids (line 19033) — this is the correct replacement field.

2. Remove parent_id and parent_type from inline response examples

These are in article endpoint response examples. Remove the parent_id and parent_type lines from each:

Endpoint	Example name	Lines to remove
GET /articles (list)	successful	1225: parent_id: 143, 1226: parent_type: collection
POST /articles (create)	article created	1280: parent_id: 145, 1281: parent_type: collection
GET /articles/{id} (retrieve)	Article found	1394: parent_id: 148, 1395: parent_type: collection
PUT /articles/{id} (update)	successful	1479: parent_id: 151, 1480: parent_type: collection
GET /articles/search	Search successful	1663: parent_id:, 1664: parent_type:

3. DO NOT change request schemas or request examples

The PR only modifies the response presenter. These stay unchanged:

• create_article_request schema (line 21843–21851) — still accepts parent_id/parent_type as input
• update_article_request schema (line 27659–27667) — same
• POST /articles request example (line 1347–1348) — parent_id: 145, parent_type: collection

4. DO NOT change collection-related parent_id fields

These are unrelated to articles and must stay:

• collection schema (line 19664) — collection hierarchy
• update_collection_request schema (line 27719) — collection hierarchy
• Collection endpoint examples (lines 2059, 2070, 2122, 2205, 2273)

Implementation Steps

1. Edit descriptions/0/api.intercom.io.yaml:
   • Remove parent_id + parent_type from article_list_item schema properties (lines ~19027–19046)
   • Remove parent_id + parent_type from each of the 5 response examples listed above
2. Validate YAML syntax: python3 -c "import yaml; yaml.safe_load(open('descriptions/0/api.intercom.io.yaml'))" && echo "YAML valid"
3. Try fern check if available (install with npm install -g fern-api if needed; use export PATH="$HOME/.nvm/versions/node/v24.10.0/bin:$PATH" first)

Verification

1. YAML valid — no syntax errors
2. fern check passes (or manual validation)
3. grep check — confirm no parent_id or parent_type remain in article response schemas/examples:

   # Should return 0 article-related hits (only collection-related ones remain)
   grep -n 'parent_id\|parent_type' descriptions/0/api.intercom.io.yaml

4. Spot-check — read the article_list_item schema to confirm parent_ids is still present and the surrounding properties are intact

Non-changes (explicit)

• Stable specs (descriptions/2.7/ through descriptions/2.15/) — untouched, these versions still include parent_id/parent_type
• Fern overrides — no changes needed (this doesn't add new endpoints)
• Request schemas — still accept parent_id/parent_type as input (PR only changes responses)

Parthas Order (task/issue)

Generate OpenAPI spec changes for locale parameter on article creation

Problem

PR intercom/intercom#491162 adds the locale parameter to the article creation API in the intercom monolith, but the public OpenAPI spec in this repo does not reflect it yet. API consumers have no documented way to specify the locale when creating articles.

Why This Matters

Customers with multi-Help-Center workspaces need to control the locale of articles created via the API. The parameter will exist in production once the monolith PR merges, but will be invisible in documentation and SDKs until the spec is updated here.

Goal

The OpenAPI spec should reflect the locale parameter changes from intercom/intercom#491162, covering the correct API versions with proper schema definitions and inline examples.

Context

• Source PR: https://github.com/intercom/intercom/pull/491162
• This repo has the generate-openapi-from-pr skill — use /generate-openapi-from-pr https://github.com/intercom/intercom/pull/491162 to analyze the PR and generate the spec changes
• The skill handles fetching the diff, analyzing version changes, and producing the YAML updates

Acceptance Criteria

• OpenAPI spec updated with the locale field on the create article request for the correct API version(s)
• Field includes type, description, example, and nullable annotation as appropriate
• All inline response examples that reference the affected schema are updated
• fern check passes (or YAML validation if fern unavailable)

Non-Goals

• Syncing to developer-docs (separate follow-up)
• SDK releases (manual workflow dispatch after merge)

_{Generated with Claude Code, zen coded with Parthas}