# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Forge Recipes API
  version: 1.0.0
extends: openapi/laravel-recipes-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: 14
- target: $.paths['/orgs/{organization}/recipes'].get
  update:
    x-apievangelist-phrasing:
      intent: List my organization's recipes
      effect: read
      questions:
      - Which bash recipes has my organization saved in Forge?
      - Where can I see all the custom scripts we can run on servers?
      instructions:
      - text: List the recipes in organization {organization}.
        slots:
          organization: path.organization
      - text: Show our saved recipes in {organization}, {size} per page.
        slots:
          organization: path.organization
          size: query.page[size]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/recipes'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a reusable server recipe
      effect: write
      questions:
      - How do I save a bash script as a recipe I can run on many servers?
      - Can I choose which Linux user a new recipe runs as?
      instructions:
      - text: Create a recipe named {name} in {organization} that runs {script} as {user}.
        slots:
          name: requestBody.name
          organization: path.organization
          script: requestBody.script
          user: requestBody.user
      - text: Save script {script} as recipe {name} running as user {user}.
        slots:
          script: requestBody.script
          name: requestBody.name
          user: requestBody.user
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/recipes/{recipe}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one of my recipes
      effect: read
      questions:
      - What script does a particular recipe of ours contain?
      - Which user does one of our saved recipes run as?
      instructions:
      - text: Show recipe {recipe} in organization {organization}.
        slots:
          recipe: path.recipe
          organization: path.organization
      - text: Get the script and user for our recipe {recipe}.
        slots:
          recipe: path.recipe
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/recipes/{recipe}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit a saved recipe
      effect: write
      questions:
      - Can I change the script inside an existing recipe?
      - How do I rename a recipe or change the user it runs as?
      instructions:
      - text: Update the script of recipe {recipe} in {organization} to {script}.
        slots:
          recipe: path.recipe
          organization: path.organization
          script: requestBody.script
      - text: Rename recipe {recipe} to {name}.
        slots:
          recipe: path.recipe
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/recipes/{recipe}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a saved recipe
      effect: destructive
      questions:
      - How do I remove a recipe we no longer use?
      - Can I delete a custom recipe from my organization?
      instructions:
      - text: Delete recipe {recipe} from organization {organization}.
        slots:
          recipe: path.recipe
          organization: path.organization
      - text: Remove our recipe {recipe}.
        slots:
          recipe: path.recipe
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/recipes/{recipe}/runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List past runs of a recipe
      effect: read
      questions:
      - Where can I see every time a recipe was run?
      - Has our recipe been executed on servers recently?
      instructions:
      - text: List the runs of recipe {recipe} in {organization}.
        slots:
          recipe: path.recipe
          organization: path.organization
      - text: Show the run history for recipe {recipe}.
        slots:
          recipe: path.recipe
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/recipes/{recipe}/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Run one of my recipes on servers
      effect: write
      questions:
      - How do I run our custom recipe across several servers at once?
      - Can I get an email with the output after a recipe finishes?
      instructions:
      - text: Run recipe {recipe} in {organization} on servers {servers}.
        slots:
          recipe: path.recipe
          organization: path.organization
          servers: requestBody.servers
      - text: 'Execute our recipe {recipe} on {servers} and email me: {email}.'
        slots:
          recipe: path.recipe
          servers: requestBody.servers
          email: requestBody.email
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/recipes/{recipe}/runs/{log}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the result of a recipe run
      effect: read
      questions:
      - What was the output of one specific recipe run?
      - Did a particular run of my recipe succeed?
      instructions:
      - text: Show run {log} of recipe {recipe} in {organization}.
        slots:
          log: path.log
          recipe: path.recipe
          organization: path.organization
      - text: Get the output of recipe {recipe} run {log}.
        slots:
          recipe: path.recipe
          log: path.log
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/teams/{team}/recipes'].get
  update:
    x-apievangelist-phrasing:
      intent: List recipes shared with a team
      effect: read
      questions:
      - Which recipes can a given team use?
      - What recipes have been shared with my team?
      instructions:
      - text: List recipes shared with team {team} in organization {organization}.
        slots:
          team: path.team
          organization: path.organization
      - text: Show the recipes team {team} has access to.
        slots:
          team: path.team
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/teams/{team}/recipes'].post
  update:
    x-apievangelist-phrasing:
      intent: Share a recipe with a team
      effect: write
      questions:
      - Can I let another team run one of our recipes?
      - How do I share a recipe with a team?
      instructions:
      - text: Share recipe {recipe_id} with team {team} in {organization}.
        slots:
          recipe_id: requestBody.recipe_id
          team: path.team
          organization: path.organization
      - text: Give team {team} access to recipe {recipe_id}.
        slots:
          team: path.team
          recipe_id: requestBody.recipe_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/orgs/{organization}/teams/{team}/recipes/{recipe}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop sharing a recipe with a team
      effect: destructive
      questions:
      - How do I take a recipe away from a team?
      - Can I unshare a recipe without deleting it?
      instructions:
      - text: Unshare recipe {recipe} from team {team} in {organization}.
        slots:
          recipe: path.recipe
          team: path.team
          organization: path.organization
      - text: Remove team {team}'s access to recipe {recipe}.
        slots:
          team: path.team
          recipe: path.recipe
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forge-recipes'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse Forge's built-in recipes
      effect: read
      questions:
      - What ready-made recipes does Laravel Forge provide?
      - Are there official recipes I can run without writing my own script?
      instructions:
      - text: List Forge's built-in recipes.
      - text: Show the next page of Forge-provided recipes after cursor {cursor}.
        slots:
          cursor: query.page[cursor]
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forge-recipes/{forgeRecipe}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a built-in Forge recipe
      effect: read
      questions:
      - What does one of the official built-in recipes actually do?
      - Can I read the script behind a provided recipe before running it?
      instructions:
      - text: Show built-in Forge recipe {forgeRecipe}.
        slots:
          forgeRecipe: path.forgeRecipe
      - text: Get the script for official recipe {forgeRecipe}.
        slots:
          forgeRecipe: path.forgeRecipe
      method: generated
      generated: '2026-10-01'
- target: $.paths['/forge-recipes/{forgeRecipe}/runs'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a built-in Forge recipe on servers
      effect: write
      questions:
      - How do I run one of the official built-in recipes on my servers?
      - Can I apply a provided recipe to several servers in one go?
      instructions:
      - text: Run built-in Forge recipe {forgeRecipe} on servers {servers}.
        slots:
          forgeRecipe: path.forgeRecipe
          servers: requestBody.servers
      - text: 'Execute official recipe {forgeRecipe} on {servers} and email the result: {email}.'
        slots:
          forgeRecipe: path.forgeRecipe
          servers: requestBody.servers
          email: requestBody.email
      method: generated
      generated: '2026-10-01'