# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Akuity Platform API — Kargo Kargo Service API
  version: 1.0.0
extends: openapi/akuity-kargoservice-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: 51
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances'].get
  update:
    x-apievangelist-phrasing:
      intent: List Kargo instances in an organization
      effect: read
      questions:
      - Which Kargo instances does my Akuity organization run?
      - Can I narrow the organization-wide Kargo instance list to one workspace with a query filter?
      instructions:
      - text: List every Kargo instance in organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Show the Kargo instances of org {organization_id}, filtered by the workspaceId query value {workspace}.
        slots:
          organization_id: path.organization_id
          workspace: query.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Kargo instance at the organization level
      effect: write
      questions:
      - How do I spin up a new managed Kargo instance for my organization?
      - Can I pick the Kargo version when provisioning an instance through the org-level endpoint?
      instructions:
      - text: Provision a Kargo instance named {name} in organization {organization_id}.
        slots:
          name: requestBody.name
          organization_id: path.organization_id
      - text: Stand up Kargo {version} as instance {name} under org {organization_id} with description {description}.
        slots:
          version: requestBody.version
          name: requestBody.name
          organization_id: path.organization_id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/promotions-events'].post
  update:
    x-apievangelist-phrasing:
      intent: Query Kargo promotion events for an organization
      effect: read
      questions:
      - What promotions have happened across all Kargo instances in my organization?
      - Is there a way to page through org-wide promotion events with a limit and offset?
      instructions:
      - text: Pull the Kargo promotion event history for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Fetch {limit} org-level promotion events for {organization_id} starting at offset {offset}.
        slots:
          limit: requestBody.limit
          organization_id: path.organization_id
          offset: requestBody.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/promotions-stats'].post
  update:
    x-apievangelist-phrasing:
      intent: Get Kargo promotion statistics for an organization
      effect: read
      questions:
      - How many Kargo promotions ran over time across my whole organization?
      - Can promotion statistics be bucketed by an interval and grouped by a field for the org?
      instructions:
      - text: Chart promotion stats for organization {organization_id} bucketed by {interval}.
        slots:
          organization_id: path.organization_id
          interval: requestBody.interval
      - text: Aggregate org {organization_id} promotion counts grouped by {group_by}.
        slots:
          organization_id: path.organization_id
          group_by: requestBody.groupByField
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/stage-specific-stats'].post
  update:
    x-apievangelist-phrasing:
      intent: Get per-stage Kargo stats for an organization
      effect: read
      questions:
      - Which Kargo stages see the most activity across my organization?
      - Where can I get stage-by-stage statistics for every Kargo instance in the org?
      instructions:
      - text: Break down Kargo activity by stage for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Get org-level stage specific stats for {organization_id} using filter {filter}.
        slots:
          organization_id: path.organization_id
          filter: requestBody.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Kargo instance by organization
      effect: destructive
      questions:
      - How do I tear down a Kargo instance I no longer need in my organization?
      - Does removing a Kargo instance through the org endpoint accept an optional workspace hint?
      instructions:
      - text: Delete Kargo instance {id} from organization {organization_id}.
        slots:
          id: path.id
          organization_id: path.organization_id
      - text: Permanently remove org {organization_id}'s Kargo instance {id}, passing workspaceId {workspace}.
        slots:
          organization_id: path.organization_id
          id: path.id
          workspace: query.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch a Kargo instance's settings (org scope)
      effect: write
      questions:
      - Can I partially change a Kargo instance's configuration without resending all of it?
      - What's the org-scoped way to apply a PATCH to one Kargo instance?
      instructions:
      - text: Patch Kargo instance {id} in organization {organization_id}.
        slots:
          id: path.id
          organization_id: path.organization_id
      - text: Apply a partial settings update to org {organization_id} Kargo instance {id}.
        slots:
          organization_id: path.organization_id
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{id}/transfer'].put
  update:
    x-apievangelist-phrasing:
      intent: Move a Kargo instance to another workspace
      effect: write
      questions:
      - How can I transfer a Kargo instance from one workspace to a different one?
      - Is it possible to reassign which workspace owns a Kargo instance using only the organization path?
      instructions:
      - text: Transfer Kargo instance {id} in organization {organization_id} to workspace {new_workspace}.
        slots:
          id: path.id
          organization_id: path.organization_id
          new_workspace: requestBody.newWorkspaceId
      - text: Reassign org {organization_id}'s instance {id} so it belongs to workspace {new_workspace}.
        slots:
          organization_id: path.organization_id
          id: path.id
          new_workspace: requestBody.newWorkspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List agents on a Kargo instance (org scope)
      effect: read
      questions:
      - Which agents are connected to my Kargo instance?
      - Can I see every Kargo agent registered to an instance using just the organization path?
      instructions:
      - text: List the agents of Kargo instance {instance_id} in organization {organization_id}.
        slots:
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Show all registered agents for org {organization_id} instance {instance_id} with workspaceId {workspace}.
        slots:
          organization_id: path.organization_id
          instance_id: path.instance_id
          workspace: query.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents'].put
  update:
    x-apievangelist-phrasing:
      intent: Apply customizations to all agents of an instance
      effect: write
      questions:
      - How do I push agent customizations to every agent of a Kargo instance at once?
      - Can bulk agent customizations be set through the organization-level Kargo route?
      instructions:
      - text: Set agent customizations {customizations} on Kargo instance {instance_id} in org {organization_id}.
        slots:
          customizations: requestBody.agentCustomizations
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Bulk-update the agent settings of organization {organization_id} instance {instance_id}.
        slots:
          organization_id: path.organization_id
          instance_id: path.instance_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new agent on a Kargo instance
      effect: write
      questions:
      - How do I add a Kargo agent for a new cluster to my instance?
      - Can I upsert a Kargo agent so it is created or updated in one call from the org route?
      instructions:
      - text: Create a Kargo agent named {name} in namespace {namespace} on instance {instance_id} of org {organization_id}.
        slots:
          name: requestBody.name
          namespace: requestBody.namespace
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Register agent {name} for organization {organization_id} Kargo instance {instance_id} with upsert set to {upsert}.
        slots:
          name: requestBody.name
          organization_id: path.organization_id
          instance_id: path.instance_id
          upsert: requestBody.upsert
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/regenerate-manifests'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate install manifests for Kargo agents
      effect: write
      questions:
      - How do I regenerate the install manifests for some or all Kargo agents?
      - Can I rebuild agent manifests for every agent on an instance via the organization path?
      instructions:
      - text: Regenerate manifests for agents {agent_names} on Kargo instance {instance_id} in org {organization_id}.
        slots:
          agent_names: requestBody.agentNames
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Rebuild install manifests for all agents of organization {organization_id} instance {instance_id}.
        slots:
          organization_id: path.organization_id
          instance_id: path.instance_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/rotate-credentials'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate credentials for Kargo agents
      effect: write
      questions:
      - How do I rotate the credentials my Kargo agents use to connect?
      - Can agent credential rotation target every agent on an instance from the org route?
      instructions:
      - text: Rotate credentials for Kargo agents {agent_names} on instance {instance_id} in org {organization_id}.
        slots:
          agent_names: requestBody.agentNames
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Issue fresh credentials to all agents of organization {organization_id} instance {instance_id}.
        slots:
          organization_id: path.organization_id
          instance_id: path.instance_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/set-maintenance-mode'].post
  update:
    x-apievangelist-phrasing:
      intent: Put Kargo agents into maintenance mode
      effect: write
      questions:
      - How do I put my Kargo agents into maintenance mode while I work on a cluster?
      - Can maintenance mode on Kargo agents expire automatically after a set time?
      instructions:
      - text: Turn maintenance mode {mode} for agents {agent_names} on instance {instance_id} in org {organization_id}.
        slots:
          mode: requestBody.maintenanceMode
          agent_names: requestBody.agentNames
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Pause every agent of organization {organization_id} instance {instance_id} for maintenance until {expiry}.
        slots:
          organization_id: path.organization_id
          instance_id: path.instance_id
          expiry: requestBody.expiry
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/version'].post
  update:
    x-apievangelist-phrasing:
      intent: Upgrade Kargo agents to a new version
      effect: write
      questions:
      - How do I upgrade my Kargo agents to a newer version?
      - Can I roll one agent version out to all agents on an instance through the org path?
      instructions:
      - text: Upgrade Kargo agents {agent_names} on instance {instance_id} in org {organization_id} to version {version}.
        slots:
          agent_names: requestBody.agentNames
          instance_id: path.instance_id
          organization_id: path.organization_id
          version: requestBody.newVersion
      - text: Move all agents of organization {organization_id} instance {instance_id} onto agent release {version}.
        slots:
          organization_id: path.organization_id
          instance_id: path.instance_id
          version: requestBody.newVersion
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one Kargo agent's details (org scope)
      effect: read
      questions:
      - What is the current state of a specific Kargo agent?
      - Can I look up a single Kargo agent by its ID using the organization path?
      instructions:
      - text: Show Kargo agent {id} on instance {instance_id} in organization {organization_id}.
        slots:
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Fetch details of agent {id} from org {organization_id} instance {instance_id}, workspaceId {workspace}.
        slots:
          id: path.id
          organization_id: path.organization_id
          instance_id: path.instance_id
          workspace: query.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update one Kargo agent's settings (org scope)
      effect: write
      questions:
      - How do I change the description or data of a single Kargo agent?
      - Can one existing agent be edited in place through the org-level Kargo route?
      instructions:
      - text: Update Kargo agent {id} on instance {instance_id} in org {organization_id} with description {description}.
        slots:
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
          description: requestBody.description
      - text: Replace the data of organization {organization_id} instance {instance_id} agent {id} with {data}.
        slots:
          organization_id: path.organization_id
          instance_id: path.instance_id
          id: path.id
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an agent from a Kargo instance (org scope)
      effect: destructive
      questions:
      - How do I remove a Kargo agent for a cluster I've decommissioned?
      - Can I delete one agent from a Kargo instance using only the organization route?
      instructions:
      - text: Delete Kargo agent {id} from instance {instance_id} in organization {organization_id}.
        slots:
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Unregister agent {id} of org {organization_id} instance {instance_id}, with workspaceId {workspace}.
        slots:
          id: path.id
          organization_id: path.organization_id
          instance_id: path.instance_id
          workspace: query.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/{id}/command'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the install command for a Kargo agent
      effect: read
      questions:
      - What command do I run on my cluster to install a Kargo agent?
      - Can the agent install command skip creating the namespace?
      instructions:
      - text: Give me the install command for Kargo agent {id} on instance {instance_id} in org {organization_id}.
        slots:
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Get the {type} install command for org {organization_id} instance {instance_id} agent {id} with skipNamespace {skip_namespace}.
        slots:
          type: query.type
          organization_id: path.organization_id
          instance_id: path.instance_id
          id: path.id
          skip_namespace: query.skipNamespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{instance_id}/agents/{id}/manifests'].get
  update:
    x-apievangelist-phrasing:
      intent: Download a Kargo agent's Kubernetes manifests
      effect: read
      questions:
      - Where do I get the raw Kubernetes manifests to deploy a Kargo agent myself?
      - Can I download a Kargo agent's manifests without the namespace object via the org route?
      instructions:
      - text: Download manifests for Kargo agent {id} on instance {instance_id} in organization {organization_id}.
        slots:
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Export org {organization_id} instance {instance_id} agent {id} YAML with skipNamespace {skip_namespace}.
        slots:
          organization_id: path.organization_id
          instance_id: path.instance_id
          id: path.id
          skip_namespace: query.skipNamespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/kargo/instances/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Kargo instance by name (org scope)
      effect: read
      questions:
      - What is the configuration and status of my Kargo instance?
      - Can I look up a Kargo instance by its name using only the organization path?
      instructions:
      - text: Show Kargo instance {name} in organization {organization_id}.
        slots:
          name: path.name
          organization_id: path.organization_id
      - text: Retrieve org {organization_id}'s instance called {name} with workspaceId {workspace}.
        slots:
          organization_id: path.organization_id
          name: path.name
          workspace: query.workspaceId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances'].get
  update:
    x-apievangelist-phrasing:
      intent: List Kargo instances in a workspace
      effect: read
      questions:
      - Which Kargo instances live inside one particular workspace?
      - Is there a workspace-scoped route that returns only that workspace's Kargo instances?
      instructions:
      - text: List Kargo instances in workspace {workspace_id} of organization {organization_id}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Enumerate what Kargo runs under workspace {workspace_id} for org {organization_id}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a Kargo instance inside a workspace
      effect: write
      questions:
      - How do I create a Kargo instance directly inside a specific workspace?
      - Can a workspace-scoped create set the instance's Kargo version and description?
      instructions:
      - text: Create Kargo instance {name} in workspace {workspace_id} of org {organization_id}.
        slots:
          name: requestBody.name
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Launch version {version} of Kargo as {name} within workspace {workspace_id}, organization {organization_id}.
        slots:
          version: requestBody.version
          name: requestBody.name
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/promotions-events'].post
  update:
    x-apievangelist-phrasing:
      intent: Query Kargo promotion events in a workspace
      effect: read
      questions:
      - What promotion events did the Kargo instances in one workspace produce?
      - Can workspace-level promotion events be filtered with a fuzzy fieldLike match?
      instructions:
      - text: List promotion events for workspace {workspace_id} in organization {organization_id}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Search workspace {workspace_id} (org {organization_id}) promotion events where field {field} is like {field_like}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
          field: requestBody.field
          field_like: requestBody.fieldLike
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/promotions-stats'].post
  update:
    x-apievangelist-phrasing:
      intent: Get Kargo promotion statistics for a workspace
      effect: read
      questions:
      - How often are promotions happening in a single workspace's Kargo instances?
      - Can I group one workspace's promotion statistics by a chosen field?
      instructions:
      - text: Summarize promotion stats for workspace {workspace_id} of org {organization_id} per {interval}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
          interval: requestBody.interval
      - text: Count workspace {workspace_id} promotions in organization {organization_id} grouped by {group_by}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
          group_by: requestBody.groupByField
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/stage-specific-stats'].post
  update:
    x-apievangelist-phrasing:
      intent: Get per-stage Kargo stats for a workspace
      effect: read
      questions:
      - Which stages are busiest in the Kargo instances of one workspace?
      - Can I get stage-level Kargo statistics scoped to a single workspace?
      instructions:
      - text: Get stage specific stats for workspace {workspace_id} in organization {organization_id}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Break down workspace {workspace_id} Kargo stages for org {organization_id} with filter {filter}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
          filter: requestBody.filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Kargo instance from a workspace
      effect: destructive
      questions:
      - How do I delete a Kargo instance that belongs to a specific workspace?
      - Is there a workspace-scoped endpoint for destroying a Kargo instance?
      instructions:
      - text: Delete Kargo instance {id} in workspace {workspace_id} of org {organization_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Destroy workspace {workspace_id}'s instance {id} under organization {organization_id}.
        slots:
          workspace_id: path.workspace_id
          id: path.id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch a Kargo instance within a workspace
      effect: write
      questions:
      - Can I partially update a Kargo instance through its workspace path?
      - What's the workspace-scoped way to PATCH a Kargo instance's settings?
      instructions:
      - text: Patch Kargo instance {id} in workspace {workspace_id} of organization {organization_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Partially modify workspace {workspace_id} instance {id} config for org {organization_id}.
        slots:
          workspace_id: path.workspace_id
          id: path.id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{id}/apply'].post
  update:
    x-apievangelist-phrasing:
      intent: Apply a declarative Kargo instance configuration
      effect: write
      questions:
      - How do I declaratively apply projects, stages and warehouses to a Kargo instance in one call?
      - Can an apply prune resource types that are no longer in my Kargo configuration?
      - Which Kargo resources can I push together, like promotion tasks, roles and repo credentials?
      instructions:
      - text: Apply stages {stages} and warehouses {warehouses} to Kargo instance {id} in workspace {workspace_id}, org {organization_id}.
        slots:
          stages: requestBody.stages
          warehouses: requestBody.warehouses
          id: path.id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Apply projects {projects} to instance {id} in workspace {workspace_id} of {organization_id} and prune {prune_types}.
        slots:
          projects: requestBody.projects
          id: path.id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
          prune_types: requestBody.pruneResourceTypes
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{id}/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a Kargo instance's full configuration
      effect: read
      questions:
      - How do I export a Kargo instance's configuration so I can keep it in Git?
      - Can I dump everything defined on a Kargo instance for backup?
      instructions:
      - text: Export Kargo instance {id} from workspace {workspace_id} in organization {organization_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Back up the declarative config of instance {id}, workspace {workspace_id}, org {organization_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{id}/transfer'].put
  update:
    x-apievangelist-phrasing:
      intent: Transfer a Kargo instance out of its current workspace
      effect: write
      questions:
      - How do I move a Kargo instance out of the workspace it currently sits in?
      - Can I hand a Kargo instance over to another workspace starting from its existing workspace path?
      instructions:
      - text: Move instance {id} from workspace {workspace_id} to workspace {new_workspace} in org {organization_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
          new_workspace: requestBody.newWorkspaceId
          organization_id: path.organization_id
      - text: Hand Kargo instance {id} currently in {workspace_id} over to {new_workspace}, organization {organization_id}.
        slots:
          id: path.id
          workspace_id: path.workspace_id
          new_workspace: requestBody.newWorkspaceId
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: List agents on a Kargo instance in a workspace
      effect: read
      questions:
      - What agents are attached to a Kargo instance in a given workspace?
      - Is there a workspace-scoped list of a Kargo instance's agents?
      instructions:
      - text: List agents for instance {instance_id} in workspace {workspace_id} of org {organization_id}.
        slots:
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Enumerate the connected clusters of workspace {workspace_id} Kargo instance {instance_id}, organization {organization_id}.
        slots:
          workspace_id: path.workspace_id
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents'].put
  update:
    x-apievangelist-phrasing:
      intent: Customize all agents of a workspace's Kargo instance
      effect: write
      questions:
      - Can I change agent customizations for a whole Kargo instance through its workspace path?
      - Where do I set shared agent customizations for an instance that lives in a workspace?
      instructions:
      - text: Apply agent customizations {customizations} to instance {instance_id} in workspace {workspace_id}, org {organization_id}.
        slots:
          customizations: requestBody.agentCustomizations
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Update every agent's customization on workspace {workspace_id} instance {instance_id} for {organization_id}.
        slots:
          workspace_id: path.workspace_id
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an agent to a workspace's Kargo instance
      effect: write
      questions:
      - How do I connect a new cluster agent to a Kargo instance in a workspace?
      - Can I create or upsert an agent on a Kargo instance through the workspace route?
      instructions:
      - text: Add agent {name} to instance {instance_id} in workspace {workspace_id} of org {organization_id}.
        slots:
          name: requestBody.name
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Upsert {upsert} a workspace {workspace_id} agent {name} in namespace {namespace} on instance {instance_id}, org {organization_id}.
        slots:
          upsert: requestBody.upsert
          workspace_id: path.workspace_id
          name: requestBody.name
          namespace: requestBody.namespace
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/regenerate-manifests'].post
  update:
    x-apievangelist-phrasing:
      intent: Regenerate agent manifests for a workspace instance
      effect: write
      questions:
      - Can I regenerate Kargo agent manifests for an instance through its workspace path?
      - Is there a workspace-scoped way to rebuild agent install manifests after a config change?
      instructions:
      - text: Regenerate agent manifests {agent_names} for instance {instance_id} in workspace {workspace_id}, org {organization_id}.
        slots:
          agent_names: requestBody.agentNames
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Recreate every agent's manifests on workspace {workspace_id} instance {instance_id} for {organization_id}.
        slots:
          workspace_id: path.workspace_id
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/rotate-credentials'].post
  update:
    x-apievangelist-phrasing:
      intent: Rotate agent credentials for a workspace instance
      effect: write
      questions:
      - Can I rotate agent credentials for a Kargo instance through its workspace path?
      - Is there a workspace-scoped route to refresh the secrets my agents use?
      instructions:
      - text: Rotate credentials of agents {agent_names} on instance {instance_id} in workspace {workspace_id}, org {organization_id}.
        slots:
          agent_names: requestBody.agentNames
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Refresh secrets for all agents of workspace {workspace_id} Kargo instance {instance_id}, {organization_id}.
        slots:
          workspace_id: path.workspace_id
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/set-maintenance-mode'].post
  update:
    x-apievangelist-phrasing:
      intent: Set maintenance mode on a workspace instance's agents
      effect: write
      questions:
      - Can I set maintenance mode on Kargo agents through the workspace path?
      - Is there a workspace-scoped way to pause agents with an expiry?
      instructions:
      - text: Set maintenance mode {mode} on agents {agent_names} of instance {instance_id}, workspace {workspace_id}, org {organization_id}.
        slots:
          mode: requestBody.maintenanceMode
          agent_names: requestBody.agentNames
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Hold all workspace {workspace_id} agents on instance {instance_id} in maintenance until {expiry} for {organization_id}.
        slots:
          workspace_id: path.workspace_id
          instance_id: path.instance_id
          expiry: requestBody.expiry
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/version'].post
  update:
    x-apievangelist-phrasing:
      intent: Upgrade agents of a workspace's Kargo instance
      effect: write
      questions:
      - Can I change the Kargo agent version through the workspace route?
      - Is there a workspace-scoped endpoint for rolling agents onto a new release?
      instructions:
      - text: Set agents {agent_names} on instance {instance_id} in workspace {workspace_id}, org {organization_id} to {version}.
        slots:
          agent_names: requestBody.agentNames
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
          version: requestBody.newVersion
      - text: Roll workspace {workspace_id} instance {instance_id} agents forward to {version} in {organization_id}.
        slots:
          workspace_id: path.workspace_id
          instance_id: path.instance_id
          version: requestBody.newVersion
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one agent of a workspace's Kargo instance
      effect: read
      questions:
      - Can I look up a single Kargo agent through its workspace path?
      - Where do I check the status of one agent on a workspace-owned Kargo instance?
      instructions:
      - text: Get agent {id} of instance {instance_id} in workspace {workspace_id}, organization {organization_id}.
        slots:
          id: path.id
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Check the status of workspace {workspace_id} Kargo agent {id} on {instance_id} for {organization_id}.
        slots:
          workspace_id: path.workspace_id
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Edit one agent of a workspace's Kargo instance
      effect: write
      questions:
      - Can I edit a single Kargo agent through its workspace path?
      - Is there a workspace-scoped route to change one agent's description?
      instructions:
      - text: 'Edit agent {id} on instance {instance_id} in workspace {workspace_id}, org {organization_id}: description {description}.'
        slots:
          id: path.id
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
          description: requestBody.description
      - text: Overwrite workspace {workspace_id} agent {id} data with {data} on instance {instance_id} for {organization_id}.
        slots:
          workspace_id: path.workspace_id
          id: path.id
          data: requestBody.data
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an agent from a workspace's Kargo instance
      effect: destructive
      questions:
      - Can I delete a Kargo agent through its workspace path?
      - Is there a workspace-scoped endpoint to drop a cluster agent from an instance?
      instructions:
      - text: Remove agent {id} from instance {instance_id} in workspace {workspace_id}, org {organization_id}.
        slots:
          id: path.id
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Drop workspace {workspace_id} Kargo agent {id} from {instance_id} for {organization_id}.
        slots:
          workspace_id: path.workspace_id
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/{id}/command'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an agent install command via a workspace
      effect: read
      questions:
      - Can I fetch the Kargo agent install command through the workspace route?
      - Does the workspace-scoped command lookup accept a location origin?
      instructions:
      - text: Fetch the install command for agent {id}, instance {instance_id}, workspace {workspace_id}, org {organization_id}.
        slots:
          id: path.id
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Build the workspace {workspace_id} agent {id} setup command on {instance_id} for {organization_id} with origin {origin}.
        slots:
          workspace_id: path.workspace_id
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
          origin: query.locationOrigin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents/{id}/manifests'].get
  update:
    x-apievangelist-phrasing:
      intent: Get agent manifests via a workspace
      effect: read
      questions:
      - Can I pull Kargo agent manifests through the workspace path?
      - Is there a workspace-scoped download of an agent's deployment YAML?
      instructions:
      - text: Pull manifests for agent {id}, instance {instance_id}, workspace {workspace_id}, organization {organization_id}.
        slots:
          id: path.id
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Save workspace {workspace_id} agent {id} deployment YAML from {instance_id} in {organization_id}, skipNamespace {skip_namespace}.
        slots:
          workspace_id: path.workspace_id
          id: path.id
          instance_id: path.instance_id
          organization_id: path.organization_id
          skip_namespace: query.skipNamespace
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a Kargo instance by name within a workspace
      effect: read
      questions:
      - Can I look up a Kargo instance by name inside a particular workspace?
      - Is there a workspace-scoped way to read one Kargo instance's details?
      instructions:
      - text: Get Kargo instance {name} from workspace {workspace_id} of org {organization_id}.
        slots:
          name: path.name
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Read details of workspace {workspace_id}'s instance named {name}, organization {organization_id}.
        slots:
          workspace_id: path.workspace_id
          name: path.name
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/orgs/{organization_id}/kargo/instances'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream changes to Kargo instances in an organization
      effect: read
      questions:
      - How can I get live updates when any Kargo instance in my organization changes?
      - Can I watch a single Kargo instance's changes as a stream?
      instructions:
      - text: Watch organization {organization_id} for Kargo instance changes.
        slots:
          organization_id: path.organization_id
      - text: Stream live updates for Kargo instance {instance} in org {organization_id}.
        slots:
          instance: query.instanceId
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/orgs/{organization_id}/kargo/instances/{instance_id}/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream changes to a Kargo instance's agents
      effect: read
      questions:
      - How do I subscribe to live agent status changes on a Kargo instance?
      - Can I watch only agents whose names fall in a range?
      instructions:
      - text: Watch the agents of Kargo instance {instance_id} in organization {organization_id}.
        slots:
          instance_id: path.instance_id
          organization_id: path.organization_id
      - text: Stream updates for agent {agent} on org {organization_id} instance {instance_id}.
        slots:
          agent: query.agentId
          organization_id: path.organization_id
          instance_id: path.instance_id
      - text: Follow agent changes on {instance_id} in {organization_id} for names from {min_name} to {max_name}.
        slots:
          instance_id: path.instance_id
          organization_id: path.organization_id
          min_name: query.minAgentName
          max_name: query.maxAgentName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream changes to Kargo instances in a workspace
      effect: read
      questions:
      - Can I get a live feed of Kargo instance changes limited to one workspace?
      - Is there a workspace-scoped stream for instance updates?
      instructions:
      - text: Subscribe to Kargo instance events in workspace {workspace_id} of {organization_id}.
        slots:
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Follow workspace {workspace_id} instance {instance} live for organization {organization_id}.
        slots:
          workspace_id: path.workspace_id
          instance: query.instanceId
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/stream/orgs/{organization_id}/workspaces/{workspace_id}/kargo/instances/{instance_id}/agents'].get
  update:
    x-apievangelist-phrasing:
      intent: Stream agent changes for a workspace's instance
      effect: read
      questions:
      - Can I stream Kargo agent updates through the workspace path?
      - Is there a workspace-scoped live feed of an instance's agents?
      instructions:
      - text: Subscribe to agent events on instance {instance_id} in workspace {workspace_id}, org {organization_id}.
        slots:
          instance_id: path.instance_id
          workspace_id: path.workspace_id
          organization_id: path.organization_id
      - text: Tail workspace {workspace_id} agent {agent} on {instance_id} live for {organization_id}.
        slots:
          workspace_id: path.workspace_id
          agent: query.agentId
          instance_id: path.instance_id
          organization_id: path.organization_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ext-api/v1/argocd/extensions/kubevision/orgs/{organization_id}/kargo/instances/promotions-events'].post
  update:
    x-apievangelist-phrasing:
      intent: Get promotion events via the KubeVision extension
      effect: read
      questions:
      - Can the Argo CD KubeVision extension show Kargo promotion events?
      - Is there a promotion-event feed served under the Argo CD extension API?
      instructions:
      - text: Through the KubeVision extension, fetch Kargo promotion events for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Via the Argo CD extension API, page {limit} promotion events for {organization_id} from offset {offset}.
        slots:
          limit: requestBody.limit
          organization_id: path.organization_id
          offset: requestBody.offset
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ext-api/v1/argocd/extensions/kubevision/orgs/{organization_id}/kargo/instances/promotions-stats'].post
  update:
    x-apievangelist-phrasing:
      intent: Get promotion stats via the KubeVision extension
      effect: read
      questions:
      - Can I read Kargo promotion statistics from inside the Argo CD KubeVision extension?
      - Does the extension API support interval bucketing for promotion counts?
      instructions:
      - text: Through KubeVision, get promotion stats for org {organization_id} per {interval}.
        slots:
          organization_id: path.organization_id
          interval: requestBody.interval
      - text: Via the Argo CD extension route, total {organization_id} promotions grouped by {group_by}.
        slots:
          organization_id: path.organization_id
          group_by: requestBody.groupByField
      method: generated
      generated: '2026-09-26'
- target: $.paths['/ext-api/v1/argocd/extensions/kubevision/orgs/{organization_id}/kargo/instances/stage-specific-stats'].post
  update:
    x-apievangelist-phrasing:
      intent: Get per-stage stats via the KubeVision extension
      effect: read
      questions:
      - Can the KubeVision extension in Argo CD show Kargo stats per stage?
      - Is there an extension-API route for stage-level Kargo statistics?
      instructions:
      - text: Through KubeVision, get stage specific Kargo stats for organization {organization_id}.
        slots:
          organization_id: path.organization_id
      - text: Via the Argo CD extension API, split {organization_id} Kargo activity by stage with filter {filter}.
        slots:
          organization_id: path.organization_id
          filter: requestBody.filter
      method: generated
      generated: '2026-09-26'