Add article tags limitation callout to Articles API endpoints

[markdennis22]

Why?

The developer-docs repo already has a "Tags cannot be managed via the Articles API" callout on the createArticle and updateArticle endpoints, but the canonical OpenAPI source doesn't. Without this change, a future sync from Intercom-OpenAPI would overwrite those docs.

How?

Adds the same callout (matching the existing listArticles format) to both endpoints in the v2.14 and v2.15 specs.

Implementation Plan

Plan: Add article tags limitation callout to Intercom-OpenAPI source specs

Context

You've already added a "Tags cannot be managed via the Articles API" callout to the createArticle and updateArticle endpoint descriptions in the developer-docs repo (versions @2.14, @2.15, @unstable) on branch docs/article-tags-limitation-note.

However, the Intercom-OpenAPI repo (intercom/Intercom-OpenAPI) is the canonical source of these specs and still has the unmodified descriptions. Without updating the source, a future sync could overwrite your developer-docs changes. This plan adds the same callout to the Intercom-OpenAPI source specs as a separate PR.

Files to modify (4 edits across 2 files)

1. Intercom-OpenAPI/descriptions/2.14/api.intercom.io.yaml

• createArticle (line 1044): Replace single-line description with quoted multi-line + callout
• updateArticle (lines 1239–1240): Replace two-line description with quoted multi-line + callout

2. Intercom-OpenAPI/descriptions/2.15/api.intercom.io.yaml

• createArticle (line 1044): Same change as 2.14
• updateArticle (lines 1239–1240): Same change as 2.14

Exact changes

Match the existing listArticles callout format (lines 980–984 in the same files):

createArticle — replace:

      description: You can create a new article by making a POST request to `https://api.intercom.io/articles`.

with:

      description: "You can create a new article by making a POST request to `https://api.intercom.io/articles`.\n\n>
        \U0001F4D8 Tags cannot be managed via the Articles API\n>\n> While article tags are
        returned in API responses, you cannot create, update, or delete tags through
        the `/articles` endpoints. To manage article tags, use the Intercom UI or
        the dedicated Tags API endpoints.\n"

updateArticle — replace:

      description: You can update the details of a single article by making a PUT
        request to `https://api.intercom.io/articles/<id>`.

with:

      description: "You can update the details of a single article by making a PUT
        request to `https://api.intercom.io/articles/<id>`.\n\n> \U0001F4D8 Tags cannot be
        managed via the Articles API\n>\n> While article tags are returned in API
        responses, you cannot create, update, or delete tags through the `/articles`
        endpoints. To manage article tags, use the Intercom UI or the dedicated Tags
        API endpoints.\n"

Steps

1. cd Intercom-OpenAPI && git checkout main && git pull
2. git checkout -b docs/article-tags-limitation-note
3. Apply all 4 edits (2 endpoints × 2 versions)
4. Validate YAML: node -e "require('js-yaml').load(require('fs').readFileSync(...))" for both files
5. Commit and create PR via gh pr create

Verification

• YAML validation passes for both modified files
• git diff shows 4 description changes matching the developer-docs callout format
• PR created in intercom/Intercom-OpenAPI repo

_{Generated with Claude Code}