# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Optimizely CMP Open API Documentation Structured Contents…
  version: 1.0.0
extends: openapi/optimizely-structured-contents-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 17
- target: $.paths['/structured-content/content-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List structured content types
      effect: read
      questions:
      - Which structured content types are defined in my Optimizely CMP?
      - Can I list only the disabled structured content types, or those from one source?
      instructions:
      - text: List all structured content types.
      - text: List structured content types from source {source} with disabled set to {disabled}.
        slots:
          source: query.source
          disabled: query.disabled
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a structured content type
      effect: write
      questions:
      - How do I define a new structured content type with its own field definitions?
      - Can I set the expected locales when I create a content type?
      instructions:
      - text: Create a structured content type with details {details} and field definitions {field_definitions}, created by {created_by}.
        slots:
          details: requestBody.details
          field_definitions: requestBody.field_definitions
          created_by: requestBody.created_by
      - text: Create a new content type from source {source} expecting locales {expected_locales}, fields {field_definitions}, details {details}, by user {created_by}.
        slots:
          source: requestBody.source
          expected_locales: requestBody.expected_locales
          field_definitions: requestBody.field_definitions
          details: requestBody.details
          created_by: requestBody.created_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a structured content type
      effect: read
      questions:
      - What does a single structured content type look like when I fetch it by ID?
      - Where can I see the details of one specific content type?
      instructions:
      - text: Show me structured content type {content_type_id}.
        slots:
          content_type_id: path.content_type_id
      - text: Fetch the definition of content type {content_type_id}.
        slots:
          content_type_id: path.content_type_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Update a structured content type's details
      effect: write
      questions:
      - Can I rename or change the details of an existing structured content type?
      - Is it possible to update a content type's source metadata after it was created?
      instructions:
      - text: Update the details of content type {content_type_id} to {details}, recorded as updated by {updated_by}.
        slots:
          content_type_id: path.content_type_id
          details: requestBody.details
          updated_by: requestBody.updated_by
      - text: Change the source metadata of content type {content_type_id} to {source_metadata} with details {details}, by user {updated_by}.
        slots:
          content_type_id: path.content_type_id
          source_metadata: requestBody.source_metadata
          details: requestBody.details
          updated_by: requestBody.updated_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/versions'].get
  update:
    x-apievangelist-phrasing:
      intent: List versions of a content type
      effect: read
      questions:
      - What versions exist for a given structured content type?
      - Can I see the version history of a content type's schema?
      instructions:
      - text: List all versions of content type {content_type_id}.
        slots:
          content_type_id: path.content_type_id
      - text: Show the version history for content type {content_type_id}.
        slots:
          content_type_id: path.content_type_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/versions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new version to a content type
      effect: write
      questions:
      - How do I publish a new version of a content type with changed field definitions?
      - Can a new content type version expect different locales than the previous one?
      instructions:
      - text: Add a new version to content type {content_type_id} with field definitions {field_definitions}, created by {created_by}.
        slots:
          content_type_id: path.content_type_id
          field_definitions: requestBody.field_definitions
          created_by: requestBody.created_by
      - text: Create a version of content type {content_type_id} expecting locales {expected_locales} with fields {field_definitions}, by {created_by}.
        slots:
          content_type_id: path.content_type_id
          expected_locales: requestBody.expected_locales
          field_definitions: requestBody.field_definitions
          created_by: requestBody.created_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/versions/{version_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one version of a content type
      effect: read
      questions:
      - How can I inspect the field definitions of one specific content type version?
      - What did a content type look like at a particular version?
      instructions:
      - text: Show version {version_id} of content type {content_type_id}.
        slots:
          version_id: path.version_id
          content_type_id: path.content_type_id
      - text: Fetch the field definitions in version {version_id} of content type {content_type_id}.
        slots:
          version_id: path.version_id
          content_type_id: path.content_type_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/contents/{content_id}/migration'].post
  update:
    x-apievangelist-phrasing:
      intent: Migrate a content item to a content type version
      effect: write
      questions:
      - How do I move a single piece of structured content onto a newer content type version?
      - Can I supply field values while migrating one content item to a new version?
      instructions:
      - text: Migrate content {content_id} to content type version {new_content_type_version_id}, performed by {created_by}.
        slots:
          content_id: path.content_id
          new_content_type_version_id: requestBody.new_content_type_version_id
          created_by: requestBody.created_by
      - text: Migrate content {content_id} to version {new_content_type_version_id} with fields {fields}, by user {created_by}.
        slots:
          content_id: path.content_id
          new_content_type_version_id: requestBody.new_content_type_version_id
          fields: requestBody.fields
          created_by: requestBody.created_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/contents/{content_id}/versions/{version_id}/previews/{preview_id}/acknowledge'].post
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge a content preview request
      effect: write
      questions:
      - How does my integration claim a content preview request before rendering it?
      - Can a content preview be acknowledged more than once?
      instructions:
      - text: Acknowledge preview {preview_id} for version {version_id} of content {content_id} with content hash {content_hash}, as user {acknowledged_by}.
        slots:
          preview_id: path.preview_id
          version_id: path.version_id
          content_id: path.content_id
          content_hash: requestBody.content_hash
          acknowledged_by: requestBody.acknowledged_by
      - text: Claim preview request {preview_id} on content {content_id} version {version_id}, hash {content_hash}, acknowledged by {acknowledged_by}.
        slots:
          preview_id: path.preview_id
          content_id: path.content_id
          version_id: path.version_id
          content_hash: requestBody.content_hash
          acknowledged_by: requestBody.acknowledged_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/contents/{content_id}/versions/{version_id}/previews/{preview_id}/complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete a content preview with rendered previews
      effect: write
      questions:
      - How do I send the finished preview renderings back for a content version?
      - What do I submit to mark a content preview request as complete?
      instructions:
      - text: Complete preview {preview_id} for content {content_id} version {version_id} with keyed previews {keyed_previews}.
        slots:
          preview_id: path.preview_id
          content_id: path.content_id
          version_id: path.version_id
          keyed_previews: requestBody.keyed_previews
      - text: Submit the rendered previews {keyed_previews} to finish preview {preview_id} of content {content_id}, version {version_id}.
        slots:
          keyed_previews: requestBody.keyed_previews
          preview_id: path.preview_id
          content_id: path.content_id
          version_id: path.version_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/managed-migrations'].get
  update:
    x-apievangelist-phrasing:
      intent: List managed migration jobs for a content type
      effect: read
      questions:
      - Which managed migration jobs have been set up for a content type?
      - Can I get a summary of how many contents succeeded or errored in each migration job?
      instructions:
      - text: List managed migration jobs for content type {content_type_id}.
        slots:
          content_type_id: path.content_type_id
      - text: List migration jobs on content type {content_type_id} with the content migration summary, {limit} at a time from offset {offset}.
        slots:
          content_type_id: path.content_type_id
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/managed-migrations'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a managed migration job
      effect: write
      questions:
      - How do I set up a bulk migration of all content from an older content type version?
      - Can I give default values for new fields when creating a managed migration job?
      instructions:
      - text: Create a managed migration for content type {content_type_id} from source version {source_content_type_version_id}, created by {created_by}.
        slots:
          content_type_id: path.content_type_id
          source_content_type_version_id: requestBody.source_content_type_version_id
          created_by: requestBody.created_by
      - text: Set up a migration job on content type {content_type_id} from version {source_content_type_version_id} using defaults {default_values}, by {created_by}.
        slots:
          content_type_id: path.content_type_id
          source_content_type_version_id: requestBody.source_content_type_version_id
          default_values: requestBody.default_values
          created_by: requestBody.created_by
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/managed-migrations/{job_id}/start'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a managed migration job
      effect: write
      questions:
      - How do I kick off a managed migration job I already created?
      - What call actually runs a pending content type migration?
      instructions:
      - text: Start managed migration job {job_id} on content type {content_type_id}.
        slots:
          job_id: path.job_id
          content_type_id: path.content_type_id
      - text: Run the not-yet-started migration {job_id} for content type {content_type_id} now.
        slots:
          job_id: path.job_id
          content_type_id: path.content_type_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/managed-migrations/{job_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a managed migration job's details
      effect: read
      questions:
      - What is the current state of a specific managed migration job?
      - Can I check the default values configured on one migration job?
      instructions:
      - text: Show migration job {job_id} for content type {content_type_id}.
        slots:
          job_id: path.job_id
          content_type_id: path.content_type_id
      - text: Check the progress of managed migration {job_id} on content type {content_type_id}.
        slots:
          job_id: path.job_id
          content_type_id: path.content_type_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/managed-migrations/{job_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a not-started managed migration job
      effect: destructive
      questions:
      - Can I remove a managed migration job that hasn't started yet?
      - Is it possible to delete a migration job once it is already running?
      instructions:
      - text: Delete managed migration job {job_id} from content type {content_type_id}.
        slots:
          job_id: path.job_id
          content_type_id: path.content_type_id
      - text: Cancel the unstarted migration {job_id} on content type {content_type_id} by deleting it.
        slots:
          job_id: path.job_id
          content_type_id: path.content_type_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/managed-migrations/{job_id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change a managed migration job's default values
      effect: write
      questions:
      - Can I change the default field values on a migration job before it runs?
      - How do I edit an existing managed migration job?
      instructions:
      - text: Set the default values of migration job {job_id} on content type {content_type_id} to {default_values}.
        slots:
          job_id: path.job_id
          content_type_id: path.content_type_id
          default_values: requestBody.default_values
      - text: Update migration {job_id} for content type {content_type_id} so new fields default to {default_values}.
        slots:
          job_id: path.job_id
          content_type_id: path.content_type_id
          default_values: requestBody.default_values
      method: generated
      generated: '2026-09-26'
- target: $.paths['/structured-content/content-types/{content_type_id}/managed-migrations/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Check whether a managed migration is possible
      effect: read
      questions:
      - Before creating a migration job, can I check whether migrating from a version will work?
      - Will my default values be enough to migrate content from an older content type version?
      instructions:
      - text: Validate a migration of content type {content_type_id} from version {source_content_type_version_id}.
        slots:
          content_type_id: path.content_type_id
          source_content_type_version_id: requestBody.source_content_type_version_id
      - text: Dry-run check migrating content type {content_type_id} from version {source_content_type_version_id} with defaults {default_values}.
        slots:
          content_type_id: path.content_type_id
          source_content_type_version_id: requestBody.source_content_type_version_id
          default_values: requestBody.default_values
      method: generated
      generated: '2026-09-26'