> ## Documentation Index
> Fetch the complete documentation index at: https://docs.akapulu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Scenario

> Update a scenario. If `hosted_links` is present, omitted links are deleted (full reconcile). Omit `hosted_links` to leave existing links unchanged.

Update a scenario's name, `nodes_json`, and optional LLM model.

Required request fields:

* `id` of the scenario to update
* `name`
* `nodes_json`

<Warning>
  If you send `hosted_links`, the array is a **full replace**. Links omitted from the array are deleted. Include each existing link's `id` to keep or edit it. Omit `hosted_links` entirely to leave existing links unchanged.
</Warning>


## OpenAPI

````yaml openapi/akapulu.json POST /scenarios/update
openapi: 3.1.0
info:
  title: Akapulu Labs API
  version: 1.0.0
  description: Public Akapulu Labs API reference.
servers:
  - url: https://akapulu.com/api
security:
  - bearerAuth: []
paths:
  /scenarios/update:
    post:
      tags:
        - Scenarios
      summary: Update scenario
      description: >-
        Update a scenario. If `hosted_links` is present, omitted links are
        deleted (full reconcile). Omit `hosted_links` to leave existing links
        unchanged.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScenarioRequest'
            examples:
              default:
                value:
                  id: 11111111-2222-3333-4444-555555555555
                  name: Sales Qualification v2
                  llm_model: gpt-4.1-mini
                  nodes_json:
                    initial_node: intro
                    role_instruction: You are a closer.
                    nodes:
                      intro:
                        task_instruction: Greet the visitor.
                        respond_immediately: true
      responses:
        '200':
          description: Scenario updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScenarioMutationResponse'
              examples:
                success:
                  value:
                    status: updated
                    id: 11111111-2222-3333-4444-555555555555
                    hosted_links: []
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                default:
                  value:
                    error: id is required
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                invalid_key:
                  value:
                    error: Invalid API key
        '404':
          description: Scenario not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                default:
                  value:
                    error: ConversationConfig not found
components:
  schemas:
    UpdateScenarioRequest:
      type: object
      required:
        - id
        - name
        - nodes_json
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        nodes_json:
          $ref: '#/components/schemas/NodesJson'
        llm_model:
          $ref: '#/components/schemas/LlmModel'
        hosted_links:
          type: array
          items:
            $ref: '#/components/schemas/HostedLinkWrite'
          description: >-
            If present, this array is the full set of hosted links after the
            update. Links omitted from the array are deleted. Omit this field to
            leave existing links unchanged.
    ScenarioMutationResponse:
      type: object
      required:
        - status
        - id
        - hosted_links
      properties:
        status:
          type: string
        id:
          type: string
          format: uuid
        hosted_links:
          type: array
          items:
            $ref: '#/components/schemas/HostedLink'
        redirect_url:
          type: string
          description: Dashboard path. Ignore for API clients.
    ApiError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message.
    NodesJson:
      type: object
      description: Scenario flow JSON. See the Using JSON guide for the full contract.
      additionalProperties: true
      properties:
        initial_node:
          type: string
        role_instruction:
          type: string
        nodes:
          type: object
          additionalProperties: true
    LlmModel:
      type: string
      description: >-
        OpenAI chat model for this scenario. Defaults to gpt-4.1-mini. Full-size
        models require a paid plan.
      enum:
        - gpt-4.1-nano
        - gpt-4.1-mini
        - gpt-4.1
        - gpt-5.4-nano
        - gpt-5.4-mini
        - gpt-5.4
    HostedLinkWrite:
      type: object
      required:
        - avatar_id
      properties:
        id:
          type: string
          format: uuid
          description: >-
            Existing hosted link ID. Required to keep/update a link on scenario
            update. Omit to create a new link.
        avatar_id:
          type: string
          format: uuid
        label:
          type: string
          maxLength: 255
        runtime_vars:
          type: object
          additionalProperties: true
          description: >-
            Must include a key for every {{runtime.*}} variable the scenario
            references. Blank values are allowed.
        stt_keywords:
          type: array
          items:
            type: string
          maxItems: 5
        record_conversation:
          type: boolean
          default: false
        redirect_url:
          type: string
          description: Optional http(s) URL to send the visitor after the call ends.
    HostedLink:
      type: object
      required:
        - id
        - token
        - url
        - label
        - scenario_id
        - avatar_id
        - runtime_vars
        - stt_keywords
        - record_conversation
        - redirect_url
        - created_at
      properties:
        id:
          type: string
          format: uuid
        token:
          type: string
        url:
          type: string
          description: >-
            Public hosted-link URL, for example
            https://live.akapulu.com/session/<token>.
        label:
          type: string
        scenario_id:
          type: string
          format: uuid
        avatar_id:
          type: string
          format: uuid
        runtime_vars:
          type: object
          additionalProperties: true
        stt_keywords:
          type: array
          items:
            type: string
        record_conversation:
          type: boolean
        redirect_url:
          type: string
        created_at:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````