---
title: "update instance"
method: PUT
path: "/instances/{id}"
tags: ["instances"]
---

# update instance

`PUT /instances/{id}`

## Request

- Base URL: `https://waapi.app/api/v1`
- URL: `https://waapi.app/api/v1/instances/{id}`
- Auth: HTTP bearer

Update the instance.

## Path parameters

- `id` integer, required

## Request body

- InstanceUpdate: Send protection is managed on the instance page in your account, not through the API.
  - `name` string
  - `webhook` object
    - `url` string
    - `events` EventType[]
  - `call_policy` CallPolicy, nullable: How the instance handles incoming calls. `null` or mode `ignore` means the call webhook fires and nothing else. Two requirements the schema cannot express: reject_with_message requires message, and answer_and_play requires audio_url or video_url — without them the request is answered with a 422.
    - `mode` 'ignore' | 'reject' | 'reject_with_message' | 'answer_and_play', required
    - `message` string, nullable: Text sent to the caller after rejecting (mode reject_with_message)
    - `audio_url` string, uri, nullable: wav, mp3 or ogg played into the call (mode answer_and_play), max 25 MB
    - `video_url` string, uri, nullable: mp4 (H.264) looped as the camera on video calls (mode answer_and_play), max 25 MB
    - `hangup_after_seconds` integer: Hang up at the latest this many seconds after the call connected (mode answer_and_play)

## Response `200`

returns the updated instance.

- object
  - `data` InstanceClientStatus
    - `status` 'success' | 'error'
    - `instanceId` string
    - `name` string
    - `data` object, nullable: Reserved. `null` in every observed response.
    - `instanceStatus` 'booting' | 'loading_screen' | 'qr' | 'authenticated' | 'auth_failure' | 'ready' | 'disconnected'
    - `instanceWebhook` string
    - `instanceEvents` EventType[]
    - `instanceCallPolicy` CallPolicyNodeShape: The call policy as the instance itself runs it: the same policy as `callPolicy`, with camelCase keys. `{ "mode": "ignore" }` alone when no policy is stored; otherwise every key is present and the unused ones are `null`. Read-only — requests always use the snake_case `callPolicy`.
      - `mode` 'ignore' | 'reject' | 'reject_with_message' | 'answer_and_play', required
      - `message` string, nullable: Text sent to the caller after rejecting (mode reject_with_message)
      - `audioUrl` string, uri, nullable: wav, mp3 or ogg played into the call (mode answer_and_play), max 25 MB
      - `videoUrl` string, uri, nullable: mp4 (H.264) looped as the camera on video calls (mode answer_and_play), max 25 MB
      - `hangupAfterSeconds` integer: Hang up at the latest this many seconds after the call connected (mode answer_and_play)
    - `nodeReachable` boolean: Returned by `PUT /instances/{id}` only, and only as `false`: the update was stored but the running instance could not be reached to be told about it, so it keeps its previous settings until it reconnects. Absent whenever no such failure happened — including on every `GET /instances/{id}/client/status`, which never carries this field.
  - `links` object
    - `self` string
  - `status` 'success' | 'error'

## Other responses

- `401`: Unauthorized — invalid or missing bearer token
- `403`: Forbidden — insufficient permissions or account blocked
- `404`: Not found — instance does not exist or does not belong to you
- `409`: Conflict — instance is not ready
- `422`: Validation error — invalid or missing request parameters
- `429`: Too many requests — rate limit exceeded

---

[API](https://skmtc.dev/waapi/apis/waapi-api-2.md) · [All operations](https://skmtc.dev/waapi/apis/waapi-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/waapi/apis/waapi-api-2/revisions/490302f75576?raw)