# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Confluence Cloud REST Content states API
  version: 1.0.0
extends: openapi/confluence-content-states-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 8
- target: $.paths['/wiki/rest/api/content/{id}/state'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the status label set on a page
      effect: read
      questions:
      - What content state, like 'In progress' or 'Ready for review', is set on a page?
      - Can I see the state on the draft version rather than the published one?
      instructions:
      - text: Show the content state of page {id}.
        slots:
          id: path.id
      - text: Get the content state on the {status} version of content {id}.
        slots:
          status: query.status
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/content/{id}/state'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a content state on a page
      effect: write
      questions:
      - How do I mark a page as 'Ready for review' through the API?
      - Can I create a new custom state by giving a name and color when setting it?
      instructions:
      - text: Set content state {name} with color {color} on the {status} version of content {id}.
        slots:
          name: requestBody.name
          color: requestBody.color
          status: query.status
          id: path.id
      - text: Apply existing state {stateId} to content {id} at status {status}.
        slots:
          stateId: requestBody.id
          id: path.id
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/content/{id}/state'].delete
  update:
    x-apievangelist-phrasing:
      intent: Clear the content state from a page
      effect: destructive
      questions:
      - How do I remove the status label from a page?
      - Does clearing a page's content state publish a new version?
      instructions:
      - text: Remove the content state from content {id}.
        slots:
          id: path.id
      - text: Clear the state on the {status} version of content {id}.
        slots:
          status: query.status
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/content/{id}/state/available'].get
  update:
    x-apievangelist-phrasing:
      intent: List the states a page can be set to
      effect: read
      questions:
      - Which content states can I choose from for this page?
      - Why do only three of my custom states show up as options for a page?
      instructions:
      - text: List the content states available for content {id}.
        slots:
          id: path.id
      - text: Show which statuses I could assign to page {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/content-states'].get
  update:
    x-apievangelist-phrasing:
      intent: List my custom content states
      effect: read
      questions:
      - What custom content states have I created?
      - Can I see every personal status label I've defined, not just the recent three?
      instructions:
      - text: List all the custom content states I've created.
      - text: Show my personal content state definitions.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/space/{spaceKey}/state'].get
  update:
    x-apievangelist-phrasing:
      intent: List a space's suggested content states
      effect: read
      questions:
      - Which content states does a space suggest to its authors?
      - What status labels are defined at the space level?
      instructions:
      - text: List the suggested content states for space {spaceKey}.
        slots:
          spaceKey: path.spaceKey
      - text: Show the space-defined statuses in {spaceKey}.
        slots:
          spaceKey: path.spaceKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/space/{spaceKey}/state/settings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a space's content state settings
      effect: read
      questions:
      - Are content states turned on at all in a given space?
      - Is a space restricting custom content states to its own list?
      instructions:
      - text: Get the content state settings for space {spaceKey}.
        slots:
          spaceKey: path.spaceKey
      - text: Check whether custom states are allowed in space {spaceKey}.
        slots:
          spaceKey: path.spaceKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/wiki/rest/api/space/{spaceKey}/state/content'].get
  update:
    x-apievangelist-phrasing:
      intent: Find content in a space with a given state
      effect: read
      questions:
      - Which pages in a space are currently marked with a particular state?
      - Is the result limit capped when I expand export or styled views?
      instructions:
      - text: List content in space {spaceKey} with state {state-id}.
        slots:
          spaceKey: path.spaceKey
          state-id: query.state-id
      - text: Find up to {limit} pages in {spaceKey} marked with state {state-id}.
        slots:
          limit: query.limit
          spaceKey: path.spaceKey
          state-id: query.state-id
      method: generated
      generated: '2026-10-01'