Add content snippets endpoints to Unstable spec

[jorgeintercom]

Summary

• Adds GET /content_snippets, POST /content_snippets, GET /content_snippets/{id}, and PUT /content_snippets/{id} to the Unstable OpenAPI spec
• Adds content_snippet, content_snippet_list, and content_snippet_create_request schemas

Context

Companion to intercom/intercom#490976 which adds the implementation, and intercom/developer-docs PR which syncs the spec and adds a changelog entry.

API Versions Affected

• Unstable only (descriptions/0/)

🤖 Generated with Claude Code

[jorgeintercom]

@claude review

[jorgeintercom]

@claude review

[levindixon]

Nice work — the schemas are well-defined, error responses properly use $ref, and the global Content Snippets tag is included. Two items to fix:

1. POST /content_snippets response should be 201, not 200

The implementation in intercom#490976 returns HTTP 201 Created for the create action. The spec currently documents '200':

responses:
  '200':
    description: Content snippet created

Should be:

responses:
  '201':
    description: Content snippet created

2. Update endpoint reuses content_snippet_create_request — but update supports partial updates

The PUT endpoint references content_snippet_create_request, which has:

required:
- title
- json_blocks

But the implementation supports partial updates — you can send only title without json_blocks (the service preserves existing values). Using the same schema with required fields would cause OpenAPI validators to reject valid partial update requests.

Options:

• Create a separate content_snippet_update_request schema without required fields
• Or remove required from content_snippet_create_request and validate required fields server-side (less ideal since create needs them documented)

Everything else looks solid — consistent examples, proper error schemas, good descriptions.

[levindixon]

One more small thing from verification:

3. locale default to "en" is undocumented

The implementation defaults locale to "en" when omitted:

locale: locale || "en",

But the content_snippet_create_request schema just lists locale as an optional string with no default property. Adding default: en to the schema would make this behavior discoverable to API consumers:

locale:
  type: string
  description: The locale of the content snippet. Defaults to `en`.
  default: en
  example: en

The description field already says "Defaults to en" which is good — just missing the formal default property for OpenAPI tooling to pick up.

[levindixon]

All three review comments addressed — 201 status, separate update schema, locale default. Looks good.