---
title: "Update a virtual tour"
method: POST
path: "/api/update_virtual_tour"
tags: ["Virtual tours"]
---

# Update a virtual tour

`POST /api/update_virtual_tour`

## Request

- Base URL: `https://app.pedra.ai`
- URL: `https://app.pedra.ai/api/update_virtual_tour`
- Auth: none required

Renames the tour or its rooms, reorders or removes rooms, replaces all navigation links, and changes the navigation point style. Free and instant; validation is all-or-nothing. Returns the full tour. 409 tour_processing while the tour is building.

## Request body

- object
  - `apiKey` string, required: Account API key, sent in the request body. Get one at https://app.pedra.ai under Settings → API.
  - `tourId` string, required
  - `name` string
  - `sceneNames` object: Room names by sceneId.
  - `sceneOrder` string[]: Every sceneId exactly once; the first is where the tour opens.
  - `removeScenes` string[]: sceneIds to remove. Photos stay in the property; links touching them are dropped; at least one scene must remain.
  - `links` TourLink[]: Replaces ALL links. Each link is one direction.
    - `linkId` string: Returned only; ignored on input.
    - `fromSceneId` string, required
    - `toSceneId` string, required
    - `yaw` number, required: Horizontal angle in the fromScene photo. 0 = centre of the equirectangular photo, negative = left.
    - `pitch` number: Vertical angle. 0 = horizon.
    - `aiGenerated` boolean: Returned only: true when the AI placed this link.
  - `navigationStyle` 'white' | 'blue'
  - `navigationSize` 'small' | 'medium' | 'large'
  - `showLabels` boolean: Always show room-name labels on navigation points.
  - `language` 'en' | 'es' | 'fr' | 'de' | 'it' | 'pt': Tour page UI language and the language of AI room names. Non-English tours get a /{lang}/virtual-tour/... URL.

## Response `200`

The updated tour.

- VirtualTour
  - `tourId` string
  - `propertyId` string
  - `name` string, nullable
  - `status` 'processing' | 'ready' | 'failed'
  - `tourUrl` string: Public tour page. Stable across edits.
  - `embedCode` string: Ready-to-paste <iframe> for the tour.
  - `appUrl` string, nullable: The property in the Pedra app.
  - `shareable` boolean: false on free-plan accounts: the tour builds, but its public link shows an upgrade page.
  - `shareableNote` string: Present when shareable is false.
  - `sceneCount` integer
  - `linkCount` integer
  - `coverImageUrl` string, nullable
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `progress` object: Present while status is processing.
    - `stage` 'queued' | 'importing' | 'naming' | 'linking'
    - `done` integer
    - `total` integer
  - `error` string: Present when status is failed.
  - `lastError` string: Present on a ready tour whose last add_virtual_tour_scenes failed.
  - `failedScenes` object[]
    - `index` integer
    - `imageUrl` string
    - `error` string
  - `scenes` object[]
    - `sceneId` string
    - `name` string, nullable
    - `imageUrl` string, nullable
  - `links` TourLink[]
    - `linkId` string: Returned only; ignored on input.
    - `fromSceneId` string, required
    - `toSceneId` string, required
    - `yaw` number, required: Horizontal angle in the fromScene photo. 0 = centre of the equirectangular photo, negative = left.
    - `pitch` number: Vertical angle. 0 = horizon.
    - `aiGenerated` boolean: Returned only: true when the AI placed this link.
  - `settings` object
    - `navigationStyle` 'white' | 'blue'
    - `navigationSize` 'small' | 'medium' | 'large'
    - `showLabels` boolean
    - `language` 'en' | 'es' | 'fr' | 'de' | 'it' | 'pt'

## Other responses

- `400`: Invalid request — e.g. a photo that isn't a 2:1 360° photo, more than 50 scenes, or an unknown enum value.
- `404`: Missing, invalid, or revoked API key, or a tour/property that isn't on this account.
- `405`: Wrong HTTP method — all endpoints accept POST (credits also accepts GET).
- `409`: The tour is still being built.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/pedra/apis/pedra-api.md) · [All operations](https://skmtc.dev/pedra/apis/pedra-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pedra/apis/pedra-api/revisions/87b2e76912c8?raw)