Document article AI agent availability fields in Preview OpenAPI spec

[ib-skoric]

Why?

PR intercom/intercom#508483 added three boolean availability fields (ai_chatbot_availability, ai_copilot_availability, ai_sales_agent_availability) to article content responses on the Preview API version, but the OpenAPI spec did not document them. Without this, SDK consumers miss the fields in generated types and the API reference is inaccurate.

How?

Add the three boolean properties to both article_content and article_list_item schemas in the Preview spec, and extend inline response examples for the five article endpoints that return article bodies.

Decisions

• Updated both article_content and article_list_item so the fields surface at the top level and inside translated_content.{locale}; article and article_translated_content inherit via allOf/$ref and need no direct edits.
• Limited changes to descriptions/0/api.intercom.io.yaml since the source PR gates the fields behind the Preview version only.
• Scoped to response documentation — request schemas (create_article_request, update_article_request) and the DELETE endpoint example were left alone.
• Omitted default: false (unlike the external_page precedent) because these are response-only fields with no server-side request default.
• Used the "For multilingual articles, this will be the value of the default language's content." suffix on article_list_item to match the convention already used by sibling properties.

Review Guidance

Dimension	Score	Reasoning
Complexity	░░░░░░░░░░ 0.8	Why Single-file YAML edit with isolated, repeated insertions; no cross-cutting impact.
Unintuitiveness	░░░░░░░░░░ 0.6	Why Diff matches the PR description and plan precisely with no surprises.
Risk Surface	░░░░░░░░░░ 0.8	Why Documentation-only spec change with no runtime, auth, or data implications.

Attention: Routine review — Pure additive OpenAPI doc change matching the plan exactly — three boolean fields added to two schemas and five inline examples.

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

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

Implementation Plan

Worker Implementation Plan

Plan: Add article AI agent availability fields to OpenAPI spec

Context

PR intercom/intercom#508483 added three boolean fields — ai_chatbot_availability, ai_copilot_availability, ai_sales_agent_availability — to article content API responses in the Preview version. The intercom-openapi spec needs to document these fields so SDK consumers see them in generated types and the API docs are accurate.

Only the Preview spec (descriptions/0/api.intercom.io.yaml) needs updating. No other version files are affected.

File to modify

descriptions/0/api.intercom.io.yaml — single file, all edits below.

Understanding the schema relationships

• article schema (line ~19297) uses allOf with article_list_item + adds statistics
• article_list_item (lines 19496-19599) defines top-level article properties (title, body, state, url, folder_id, etc.)
• article_content (lines 19320-19388) defines per-locale content properties; used via article_translated_content for multilingual articles
• article_translated_content (lines 19814-19939) has locale keys that each $ref article_content
• Inline response examples show top-level article fields (matching article_list_item)

Both article_content AND article_list_item need the new fields:

• article_content: so the fields appear in translated_content.{locale}.* for multilingual articles
• article_list_item: so the fields appear at the top level of article responses (where inline examples live)

Request schemas are out of scope — the order is about response documentation.

Edits (apply bottom-up to avoid line drift)

Edit 1: article_list_item — add 3 fields after folder_id (line 19599)

Insert after line 19599 (example: 6), before line 19600 (internal_article_list_item:):

        ai_chatbot_availability:
          type: boolean
          description: Whether the article is available for AI Chatbot. For multilingual
            articles, this will be the value of the default language's content.
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the article is available for AI Copilot. For multilingual
            articles, this will be the value of the default language's content.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the article is available for AI Sales Agent. For multilingual
            articles, this will be the value of the default language's content.
          example: true

Convention note: The "For multilingual articles, this will be the value of the default language's content." suffix matches the pattern used by other article_list_item properties (title, description, body, state, etc.).

Edit 2: article_content — add 3 fields after audience_ids (line 19388)

Insert after line 19388 (- 2), before line 19389 (internal_article_list:):

        ai_chatbot_availability:
          type: boolean
          description: Whether the article is available for AI Chatbot.
          example: true
        ai_copilot_availability:
          type: boolean
          description: Whether the article is available for AI Copilot.
          example: true
        ai_sales_agent_availability:
          type: boolean
          description: Whether the article is available for AI Sales Agent.
          example: true

Edit 3: Inline response examples — add fields to 5 article endpoints

Add the 3 boolean fields after url in each article endpoint's inline response example. The fields are NOT added to the DELETE endpoint (which returns {id, object, deleted} only).

3a. GET /articles (list) — after line 1251

After url: http://help-center.test/myapp-64/en/articles/39-..., insert (22-space indent):

                      ai_chatbot_availability: true
                      ai_copilot_availability: true
                      ai_sales_agent_availability: true

3b. POST /articles (create) — after line 1313

After url: http://help-center.test/myapp-68/en/articles/42-..., insert (20-space indent):

                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true

3c. GET /articles/{id} (retrieve) — after line 1428

After url: http://help-center.test/myapp-74/en/articles/45-..., insert (20-space indent):

                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true

3d. PUT /articles/{id} (update) — after line 1512

After url: http://help-center.test/myapp-80/en/articles/48-..., insert (20-space indent):

                    ai_chatbot_availability: true
                    ai_copilot_availability: true
                    ai_sales_agent_availability: true

3e. GET /articles/search — after line 1689

After url: (null value), insert (24-space indent):

                        ai_chatbot_availability: true
                        ai_copilot_availability: true
                        ai_sales_agent_availability: true

Edit order (to avoid line drift)

Apply edits from highest line number to lowest:

1. Edit 1 — article_list_item (line 19599)
2. Edit 2 — article_content (line 19388)
3. Edit 3e — search example (line 1689)
4. Edit 3d — update example (line 1512)
5. Edit 3c — retrieve example (line 1428)
6. Edit 3b — create example (line 1313)
7. Edit 3a — list example (line 1251)

What NOT to change

Location	Reason
article_translated_content	Each locale already $refs article_content, so new fields propagate automatically
article schema	Inherits from article_list_item via allOf, so new fields propagate automatically
create_article_request / update_article_request	Out of scope — the order is about response documentation
internal_article_list_item	Internal articles are a separate concept, not in scope
DELETE /articles/{id} example	Returns {id, object, deleted} only — no content fields
Other version specs (descriptions/2.7/ through descriptions/2.15/)	Fields are Preview-only

Verification

1. Run fern check to validate the spec
2. Visually confirm:
   • article_content schema has all 3 boolean properties
   • article_list_item schema has all 3 boolean properties
   • All 5 article endpoint inline examples include the 3 fields
3. If fern check fails, read the error output carefully — likely an indentation or YAML syntax issue

Existing pattern reference

The closest precedent is ai_agent_availability / ai_copilot_availability on the external_page schema (lines ~25662-25674), which uses:

type: boolean
description: Whether the external page should be used to answer questions by AI Agent.
default: false
example: true

The new article fields omit default because they are response-only documentation (not request fields where a server-side default applies).

Parthas Order (task/issue)

Add article AI agent availability fields to OpenAPI spec

Problem

PR intercom/intercom#508483 added three boolean fields — ai_chatbot_availability, ai_copilot_availability, ai_sales_agent_availability — to article content API responses, gated behind the Preview API version via AddArticleAgentAvailabilityFields. The intercom-openapi spec does not yet document these fields on the article_content schema.

Why This Matters

Without the spec update, SDK consumers on the Preview version will not see these fields in generated types, and the API documentation will be inaccurate.

Goal

The Preview OpenAPI spec documents the three AI agent availability boolean fields on the article_content schema, with correct types, descriptions, and examples.

Context

• Source PR: https://github.com/intercom/intercom/pull/508483
• These fields are Preview-version only — only descriptions/0/api.intercom.io.yaml needs updating
• The repo has a generate-openapi-from-pr skill — use it with the source PR URL
• The article_content schema is at approximately line 19320 of the preview spec
• Note: there are already existing ai_agent_availability and ai_copilot_availability integer fields on some schemas (non-boolean, different naming) — the new fields are boolean and named with an ai_ prefix pattern (ai_chatbot_availability, ai_copilot_availability, ai_sales_agent_availability)

Acceptance Criteria

• article_content schema in descriptions/0/api.intercom.io.yaml includes ai_chatbot_availability, ai_copilot_availability, and ai_sales_agent_availability as boolean properties
• Inline response examples for article endpoints include the new fields
• fern check passes

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