Document audience targeting fields on Content Import Sources (Preview)

[ib-skoric]

Why?

PR intercom/intercom#497303 added audience targeting to the Content Import Sources public API but deferred the OpenAPI schema changes. Without this follow-up, the new audience_id and apply_audience_to_existing_content parameters are undocumented for SDK and developer-docs consumers.

How?

Update the Preview OpenAPI spec (descriptions/0/api.intercom.io.yaml) to add audience_id to the response and create/update request schemas, add apply_audience_to_existing_content to the update request schema, and include audience_id: null in the inline response examples.

Decisions

• Scoped changes to the Preview spec only, since the new parameters are gated to the Unstable/Preview API version
• Modeled audience_id as a nullable integer (matching the existing parent_folder_id pattern) so null can represent "no audience" and the explicit-remove semantics
• Left request examples unchanged since both parameters are optional and existing examples represent minimal create/update payloads
• Set audience_id: null in all response examples to reflect the default unset state

Review Guidance

Dimension	Score	Reasoning
Complexity	░░░░░░░░░░ 0.8	Why Single-file YAML additions to three schemas plus example updates, no cross-cutting impact.
Unintuitiveness	░░░░░░░░░░ 0.5	Why Diff matches the plan's line-by-line prescription precisely.
Risk Surface	░░░░░░░░░░ 0.6	Why Documentation-only spec file; no runtime, auth, or data paths touched.

Attention: Routine review — Mechanical OpenAPI spec additions matching the plan exactly — schema fields and example updates only.

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

Implementation Plan

Worker Implementation Plan

Plan: Add audience targeting fields to Content Import Source Preview spec

Context

PR intercom/intercom#497303 added audience targeting to the Content Import Sources API (POST/PUT /ai/content_sources). The OpenAPI spec changes were explicitly deferred. This order adds the missing audience_id and apply_audience_to_existing_content fields to the Preview spec (descriptions/0/api.intercom.io.yaml).

Only the Preview spec (version 0) needs updating — these parameters are gated to Unstable/Preview.

Target File

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

Changes Required

1. Response schema: content_import_source (line ~20959)

Add audience_id property before the required block (after updated_at):

        audience_id:
          type: integer
          nullable: true
          description: The unique identifier for the audience associated with this content import source.
          example: 5678

This is a nullable integer — the field is null when no audience is set (or when removed by setting to null).

2. Create request schema: create_content_import_source_request (line ~22289)

Add audience_id property after url:

        audience_id:
          type: integer
          nullable: true
          description: The unique identifier for the audience to associate with this content import source.
          example: 5678

Not required (optional on create).

3. Update request schema: update_content_import_source_request (line ~28397)

Add two properties after url:

        audience_id:
          type: integer
          nullable: true
          description: The unique identifier for the audience to associate with this content import source. Set to null to remove the audience.
          example: 5678
        apply_audience_to_existing_content:
          type: boolean
          description: When true, the audience will be applied to all existing external pages belonging to this content import source.
          default: false
          example: false

Neither is required.

4. Inline response examples — add audience_id: null to ALL response examples

Each response example for content import sources needs the new field. Add audience_id: null after existing fields in each example:

GET list (lines 637-660) — 3 items in the data array, each gets audience_id: null

• After line 644 (item 1, after updated_at: 1734537259)
• After line 652 (item 2, after updated_at: 1734537259)
• After line 660 (item 3, after updated_at: 1734537259)

POST create (lines 703-711) — after line 711 (updated_at: 1734537261)

GET single (lines 795-803) — after line 803 (updated_at: 1734537265)

PUT update (lines 838-846) — after line 846 (updated_at: 1734537267)

All examples use audience_id: null since the example scenarios don't set an audience.

5. POST create request example (lines 736-738)

No change needed — audience_id is optional and the example shows a minimal create.

6. PUT update request example (lines 871-873)

No change needed — audience_id is optional and the example shows a minimal update.

Validation

After all edits:

1. Run fern check to validate the spec (requires npm install -g fern-api or use npx)
2. Verify YAML is well-formed — indentation must be exactly 2 spaces throughout

Conventions to Follow

• 2-space YAML indentation throughout
• Nullable fields: type: integer + nullable: true (no x-nullable, see existing parent_folder_id pattern)
• Every property needs: type, description, example; add nullable when applicable
• Boolean fields with defaults: include default and example
• Response examples use literal values (not $ref)

Commit

Single commit: Add audience targeting fields to Content Import Source Preview spec

Parthas Order (task/issue)

Generate OpenAPI spec changes for audience targeting on Content Import Sources

Problem

PR intercom/intercom#497303 added audience targeting to the Content Import Sources public API (POST/PUT /ai/content_sources) but explicitly excluded OpenAPI schema changes: "OpenAPI schema changes excluded — will be handled in a separate follow-up PR." This is that follow-up.

The PR is shipping today. The OpenAPI spec needs to be updated to document the new API surface.

Why This Matters

Without the spec update, the new audience_id and apply_audience_to_existing_content parameters are undocumented — SDK users and developer-docs consumers will not know they exist.

What Changed in the Intercom Monolith

PR: https://github.com/intercom/intercom/pull/497303

Changes (Unstable/Preview API only):

• POST /ai/content_sources — new optional audience_id request parameter (integer)
• PUT /ai/content_sources/:id — new optional audience_id (integer) and apply_audience_to_existing_content (boolean, default false) request parameters
• GET /ai/content_sources/:id and GET /ai/content_sources — response now includes audience_id field (integer, nullable)
• Setting audience_id to null removes the audience
• Invalid audience_id returns 400 error
• These parameters are gated to the Unstable/Preview API version — stable versions ignore them

Goal

The Preview OpenAPI spec (descriptions/0/api.intercom.io.yaml) reflects the new audience targeting parameters and response fields.

How

Use the generate-openapi-from-pr skill with PR https://github.com/intercom/intercom/pull/497303 as input. The skill will analyze the diff and generate the appropriate YAML changes.

Acceptance Criteria

• Preview spec includes audience_id in Content Import Source request schemas (create and update)
• Preview spec includes apply_audience_to_existing_content in update request schema
• Preview spec includes audience_id in Content Import Source response schema
• All inline response examples are updated to include the new field
• fern check passes

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