Add parent_ids to article request schemas in Preview spec

[ib-skoric]

Why?

intercom#499615 made parent_ids a writable field on the Articles API (Unstable), but the Preview OpenAPI spec only reflected the response side (via #448). Without documenting parent_ids on create/update requests, customers saw the field in responses with no documented way to write it.

How?

Add parent_ids (array of integers) to create_article_request and update_article_request in the Preview spec, mirroring the existing response schema shape, and extend the POST/PUT /articles request examples to demonstrate its usage.

Decisions

• Scoped changes to the Preview spec only, since the underlying versioned change is Unstable-gated
• Kept parent_id/parent_type in request schemas since they still function as inputs when parent_ids is omitted
• Matched the parent_ids shape and example values already used in the article_list_item response schema for consistency
• Updated only the successful PUT example, leaving the article_not_found error example untouched

Review Guidance

Dimension	Score	Reasoning
Complexity	░░░░░░░░░░ 0.8	Why Single-file YAML additions in four well-scoped locations with no cross-cutting impact.
Unintuitiveness	░░░░░░░░░░ 0.6	Why Diff aligns precisely with the PR description and implementation plan — no surprises.
Risk Surface	░░░░░░░░░░ 0.9	Why Docs-only change to Preview spec; no auth, billing, data, or runtime behavior touched.

Attention: Routine review — Pure OpenAPI Preview-spec documentation addition that mirrors an existing response schema; diff matches plan exactly.

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

• Relates to https://github.com/intercom/intercom/pull/499615

Implementation Plan

Worker Implementation Plan

Plan: Add parent_ids to Article Request Schemas in Preview Spec

Context

PR intercom/intercom#499615 adds parent_ids as a writable field on the Articles API (Unstable version). PR #448 already added parent_ids to response schemas/examples in the Preview spec. This order completes the picture by adding parent_ids to the request schemas and examples, so customers can see how to write the field.

Only the Preview spec (descriptions/0/api.intercom.io.yaml) is affected — the change is gated on the RemoveArticleParentIdAndParentType versioned change (Unstable).

File to Modify

descriptions/0/api.intercom.io.yaml — the single file for all changes.

No other files should be touched. Stable specs (descriptions/2.7/ through descriptions/2.15/) must not be changed.

Reference: Existing parent_ids in Response Schema

The response schema article_list_item (line ~19280) already defines parent_ids:

parent_ids:
  type: array
  description: The ids of the article's parent collections or sections. An
    article without this field stands alone.
  items:
    type: integer
  example:
  - 18
  - 19

The request schema definitions should be consistent with this pattern.

Changes

1. Add parent_ids to create_article_request schema (line ~22110)

Location: After parent_type (line 22110), before translated_content (line 22111).

Insert:

        parent_ids:
          type: array
          description: The ids of the article's parent collections or sections.
            An article without this field stands alone.
          items:
            type: integer
          example:
          - 18
          - 19

Exact edit: Replace parent_type block ending + translated_content start:

• old: the line translated_content: at line 22111
• new: the parent_ids block followed by translated_content:

Keep parent_id and parent_type — they still work as inputs.

2. Add parent_ids to update_article_request schema (line ~28254)

Location: After parent_type (line 28254), before translated_content (line 28255).

Insert the same parent_ids block:

        parent_ids:
          type: array
          description: The ids of the article's parent collections or sections.
            An article without this field stands alone.
          items:
            type: integer
          example:
          - 18
          - 19

Exact edit: Replace parent_type block ending + translated_content start:

• old: the line translated_content: at line 28255
• new: the parent_ids block followed by translated_content:

3. Update POST /articles request example (line ~1357)

Location: Lines 1357-1358 in the article_created example.

The current example uses parent_id and parent_type. Add parent_ids alongside them (both old and new fields are valid inputs).

After parent_type: collection (line 1358), insert:

                  parent_ids:
                  - 145

This shows the array equivalent of the parent_id: 145 already in the example.

4. Update PUT /articles/{id} request example (line ~1547)

Location: Lines 1543-1547 in the successful example.

The current example is minimal (title + body only). Add parent_ids to demonstrate usage:

After body: "<p>New gifts in store for the jolly season</p>" (line 1547), insert:

                  parent_ids:
                  - 18
                  - 19

Only update the successful example, not the article_not_found example (which is an error case).

Verification

1. YAML validity: Run python3 -c "import yaml; yaml.safe_load(open('descriptions/0/api.intercom.io.yaml'))" to validate YAML syntax
2. fern check: Run export PATH="$HOME/.nvm/versions/node/v24.10.0/bin:$PATH" && npx fern-api check (if fern is available) to validate the spec
3. Stable specs unchanged: Run git diff --name-only and confirm only descriptions/0/api.intercom.io.yaml appears
4. Spot check: Read back the modified sections to confirm correct indentation and placement

Commit

Single commit: Add parent_ids to article request schemas in Preview spec

Message should reference the source PR (intercom#499615) and companion PR (#448).

Parthas Order (task/issue)

Add parent_ids to article request schemas in Preview spec (reflecting intercom#499615)

Problem

PR intercom/intercom#499615 makes parent_ids a writable field on the Articles API for the Unstable version — customers can now send parent_ids on create and update to place articles in collections. The OpenAPI Preview spec does not reflect this yet, so the new write path is invisible in documentation and SDKs.

Why This Matters

PR #448 already removed parent_id/parent_type from article responses in the Preview spec. Without adding parent_ids to the request schemas, customers see the field in responses but have no documented way to write it — the deprecation looks like a pure removal with no replacement.

Goal

The Preview OpenAPI spec should document parent_ids as an accepted field on article create and update requests, matching the write behavior added in intercom#499615.

Context

• Source PR: https://github.com/intercom/intercom/pull/499615
• Companion spec PR (response side): Deprecate parent_id and parent_type from article API responses (Preview) #448
• The change is gated on the RemoveArticleParentIdAndParentType versioned change (Unstable), so only the Preview spec (descriptions/0/api.intercom.io.yaml) should be updated
• parent_ids already exists in the response schema article_list_item (line ~19280) as an array of integers — the request schema definition should be consistent with it
• The existing parent_id/parent_type fields should remain in request schemas — they still work as inputs even on the Unstable version (when parent_ids is not provided)
• This repo has the generate-openapi-from-pr skill — use /generate-openapi-from-pr https://github.com/intercom/intercom/pull/499615 to analyze the PR and generate the spec changes

Constraints

• Preview spec only — stable specs (2.7–2.15) must not be changed
• Response schemas/examples are already correct (handled by PR Deprecate parent_id and parent_type from article API responses (Preview) #448)
• Do not remove parent_id/parent_type from request schemas — they still function as inputs

Acceptance Criteria

• create_article_request schema includes a parent_ids property (array of integers) with description and example
• update_article_request schema includes a parent_ids property (array of integers) with description and example
• Request examples for POST/PUT /articles include parent_ids usage
• fern check passes (or YAML validation if fern unavailable)
• Stable version specs are unchanged

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