API Evangelist conversational phrasing for authentik Flows API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for authentik Flows API
  version: 1.0.0
extends: openapi/authentik-flows-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: 22
- target: $.paths['/flows/bindings/'].get
  update:
    x-apievangelist-phrasing:
      intent: List flow stage bindings
      effect: read
      questions:
      - Which stages are bound to my authentik flows, and in what order?
      - Can I list only the stage bindings of one flow?
      instructions:
      - text: List all flow stage bindings.
      - text: Show the stage bindings for flow {target}.
        slots:
          target: query.target
      - text: Find where stage {stage} is bound into flows.
        slots:
          stage: query.stage
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/bindings/'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a stage to a flow
      effect: write
      questions:
      - How do I add a stage to a login flow at a specific position?
      - Can a stage binding re-evaluate policies when the stage is shown to the user?
      instructions:
      - text: Bind stage {stage} to flow {target} at order {order}.
        slots:
          stage: requestBody.stage
          target: requestBody.target
          order: requestBody.order
      - text: 'Add stage {stage} to flow {target} at position {order} and re-evaluate policies: {re_evaluate_policies}.'
        slots:
          stage: requestBody.stage
          target: requestBody.target
          order: requestBody.order
          re_evaluate_policies: requestBody.re_evaluate_policies
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/bindings/{fsb_uuid}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a flow stage binding
      effect: read
      questions:
      - What order and policy settings does a specific stage binding have?
      - How does this stage binding handle an invalid challenge response?
      instructions:
      - text: Show flow stage binding {fsb_uuid}.
        slots:
          fsb_uuid: path.fsb_uuid
      - text: Fetch the settings of stage binding {fsb_uuid}.
        slots:
          fsb_uuid: path.fsb_uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/bindings/{fsb_uuid}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a flow stage binding
      effect: write
      questions:
      - Can I overwrite every field of a stage binding in one call?
      - What must I resend when fully replacing a flow stage binding?
      instructions:
      - text: Replace stage binding {fsb_uuid} so stage {stage} sits in flow {target} at order {order}.
        slots:
          fsb_uuid: path.fsb_uuid
          stage: requestBody.stage
          target: requestBody.target
          order: requestBody.order
      - text: 'Fully rewrite binding {fsb_uuid}: flow {target}, stage {stage}, order {order}, policy mode {policy_engine_mode}.'
        slots:
          fsb_uuid: path.fsb_uuid
          target: requestBody.target
          stage: requestBody.stage
          order: requestBody.order
          policy_engine_mode: requestBody.policy_engine_mode
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/bindings/{fsb_uuid}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a stage from a flow
      effect: destructive
      questions:
      - How do I take a stage out of a flow?
      - Does deleting a stage binding delete the stage itself?
      instructions:
      - text: Delete flow stage binding {fsb_uuid}.
        slots:
          fsb_uuid: path.fsb_uuid
      - text: Unbind the stage attached by binding {fsb_uuid}.
        slots:
          fsb_uuid: path.fsb_uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/bindings/{fsb_uuid}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change part of a flow stage binding
      effect: write
      questions:
      - Can I just move a stage to a different position in its flow?
      - Is it possible to only change how invalid responses are handled on a binding?
      instructions:
      - text: Only change the order of stage binding {fsb_uuid} to {order}.
        slots:
          fsb_uuid: path.fsb_uuid
          order: requestBody.order
      - text: Set just the invalid response action of binding {fsb_uuid} to {invalid_response_action}.
        slots:
          fsb_uuid: path.fsb_uuid
          invalid_response_action: requestBody.invalid_response_action
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/bindings/{fsb_uuid}/used_by/'].get
  update:
    x-apievangelist-phrasing:
      intent: See what uses a flow stage binding
      effect: read
      questions:
      - What objects reference a particular stage binding?
      - Do any policies depend on this flow stage binding?
      instructions:
      - text: Show what references stage binding {fsb_uuid}.
        slots:
          fsb_uuid: path.fsb_uuid
      - text: List objects using flow stage binding {fsb_uuid}.
        slots:
          fsb_uuid: path.fsb_uuid
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/executor/{flow_slug}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the next challenge in a running flow
      effect: read
      questions:
      - How does a custom login UI fetch the current challenge of an authentik flow?
      - What stage is the user on in the flow they're executing right now?
      instructions:
      - text: Get the next pending challenge for flow {flow_slug} with querystring {query}.
        slots:
          flow_slug: path.flow_slug
          query: query.query
      - text: Fetch the current challenge of active flow {flow_slug}, passing query {query}.
        slots:
          flow_slug: path.flow_slug
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/executor/{flow_slug}/'].post
  update:
    x-apievangelist-phrasing:
      intent: Answer a flow challenge and advance
      effect: write
      questions:
      - How do I submit a user's answer to a flow challenge and move to the next stage?
      - Can my own frontend drive an authentik flow stage by stage?
      instructions:
      - text: Submit the response to the current challenge of flow {flow_slug} with query {query}.
        slots:
          flow_slug: path.flow_slug
          query: query.query
      - text: Solve the pending challenge in flow {flow_slug} and advance it, querystring {query}.
        slots:
          flow_slug: path.flow_slug
          query: query.query
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/inspector/{flow_slug}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Inspect a flow's current state
      effect: read
      questions:
      - How can I debug where a user is stuck in a flow?
      - Can I see the plan and history of a flow while it runs?
      instructions:
      - text: Inspect the current state of flow {flow_slug}.
        slots:
          flow_slug: path.flow_slug
      - text: Open the flow inspector for {flow_slug}.
        slots:
          flow_slug: path.flow_slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/'].get
  update:
    x-apievangelist-phrasing:
      intent: List flows
      effect: read
      questions:
      - Which flows exist in my authentik instance?
      - Can I list only the authentication flows by designation?
      instructions:
      - text: List all flows.
      - text: Show flows with designation {designation}.
        slots:
          designation: query.designation
      - text: Find flows named {name}.
        slots:
          name: query.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a flow
      effect: write
      questions:
      - How do I create a new enrollment or authentication flow?
      - Can I choose what happens when a new flow denies access?
      instructions:
      - text: Create flow {name} with slug {slug}, title {title} and designation {designation}.
        slots:
          name: requestBody.name
          slug: requestBody.slug
          title: requestBody.title
          designation: requestBody.designation
      - text: Set up a {designation} flow called {name} at slug {slug} titled {title} with layout {layout}.
        slots:
          designation: requestBody.designation
          name: requestBody.name
          slug: requestBody.slug
          title: requestBody.title
          layout: requestBody.layout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/{slug}/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a flow
      effect: read
      questions:
      - What designation and title does a given flow have?
      - Is compatibility mode enabled on this flow?
      instructions:
      - text: Show flow {slug}.
        slots:
          slug: path.slug
      - text: Fetch the settings of the flow at slug {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/{slug}/'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a flow's settings
      effect: write
      questions:
      - Can I overwrite all of a flow's settings in one request?
      - What fields are required to fully replace a flow?
      instructions:
      - text: Replace flow {slug} with name {name}, new slug {new_slug}, title {title} and designation {designation}.
        slots:
          slug: path.slug
          name: requestBody.name
          new_slug: requestBody.slug
          title: requestBody.title
          designation: requestBody.designation
      - text: 'Fully rewrite flow {slug}: name {name}, slug {new_slug}, title {title}, designation {designation}, denied action {denied_action}.'
        slots:
          slug: path.slug
          name: requestBody.name
          new_slug: requestBody.slug
          title: requestBody.title
          designation: requestBody.designation
          denied_action: requestBody.denied_action
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/{slug}/'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a flow
      effect: destructive
      questions:
      - How do I delete a flow I no longer use?
      - Is removing a flow permanent?
      instructions:
      - text: Delete flow {slug}.
        slots:
          slug: path.slug
      - text: Remove the flow at slug {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/{slug}/'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change part of a flow
      effect: write
      questions:
      - Can I just change the title shown on a flow's pages?
      - Is it possible to only turn on compatibility mode for password managers on a flow?
      instructions:
      - text: Only change the title of flow {slug} to {title}.
        slots:
          slug: path.slug
          title: requestBody.title
      - text: Set just compatibility mode on flow {slug} to {compatibility_mode}.
        slots:
          slug: path.slug
          compatibility_mode: requestBody.compatibility_mode
      - text: Change only the required authentication level of flow {slug} to {authentication}.
        slots:
          slug: path.slug
          authentication: requestBody.authentication
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/{slug}/diagram/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a flow's diagram
      effect: read
      questions:
      - Can I get a visual diagram of the stages in a flow?
      - What format is the flow diagram returned in?
      instructions:
      - text: Get the flowchart diagram for flow {slug}.
        slots:
          slug: path.slug
      - text: Draw the stage diagram of flow {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/{slug}/execute/'].get
  update:
    x-apievangelist-phrasing:
      intent: Execute a flow as the current user
      effect: read
      questions:
      - How do I run a flow as myself to test it?
      - Can I get the link to start a flow for the current user?
      instructions:
      - text: Execute flow {slug} for the current user.
        slots:
          slug: path.slug
      - text: Run flow {slug} as me.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/{slug}/export/'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a flow to YAML
      effect: read
      questions:
      - How do I export a flow so I can reuse it elsewhere?
      - Can a flow be downloaded as a .yaml file?
      instructions:
      - text: Export flow {slug} to a YAML file.
        slots:
          slug: path.slug
      - text: Download flow {slug} as .yaml.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/{slug}/used_by/'].get
  update:
    x-apievangelist-phrasing:
      intent: See what uses a flow
      effect: read
      questions:
      - Which providers, stages or brands reference a given flow?
      - What breaks if I delete this flow?
      instructions:
      - text: Show what references flow {slug}.
        slots:
          slug: path.slug
      - text: List objects that depend on flow {slug}.
        slots:
          slug: path.slug
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/cache_clear/'].post
  update:
    x-apievangelist-phrasing:
      intent: Clear the flow cache
      effect: write
      questions:
      - How do I force authentik to rebuild cached flow plans?
      - Can I flush the flow cache after changing stages?
      instructions:
      - text: Clear the flow cache.
      - text: Flush all cached flow plans.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/flows/instances/cache_info/'].get
  update:
    x-apievangelist-phrasing:
      intent: Get flow cache info
      effect: read
      questions:
      - How many flows are currently cached?
      - Can I check the state of the flow cache?
      instructions:
      - text: Show flow cache info.
      - text: Report how many flow plans are cached.
      method: generated
      generated: '2026-09-26'