API AUTHENTICATION

GET app is public and does not require authentication.

The API uses Bearer authentication over HTTPS. Sign in with POST login, sending your username and password in the request body. Use the returned user access token in the Authorization header of authenticated requests.

Authorization: Bearer USER_TOKEN

Desktop, mobile and other clients use the same endpoints and authentication. Keep credentials and refresh tokens in the HTTPS request body, and send user access tokens in the Authorization header.

Where documented, the Authorization header also accepts Bearer API_KEY. Include the user token parameter when an endpoint requires a user identity. The rooms endpoint requires a user Bearer token. Public clients should use user access tokens without embedding an API key.

Missing, expired or revoked user authentication returns HTTP 401. Authenticated requests without the required permission return HTTP 403; resources outside the user's access scope may return HTTP 404. Endpoint-specific response codes are listed below.

GET APPLICATION

GET https://vt.pageier.com/api/app

Returns the application name and logo configured in the administration settings. This endpoint is public: no login, user token or API key is required. Use HTTPS.

HEADERS

No authentication headers are required.

QUERY PARAMETERS

None.

REQUEST EXAMPLE

GET /api/app HTTP/1.1

RESPONSE

RESPONSE EXAMPLE

{
  "message": "ok",
  "data": {
    "name": "Virtual Tour Platform",
    "logo_url": "https://example.com/backend/assets/logo_123.png",
    "registration_enabled": true,
    "validate_email": true
  }
}

ERROR RESPONSES

LOGIN

POST https://vt.pageier.com/api/login

HEADERS

Sign in

BODY PARAMETERS

REQUEST EXAMPLE

{
  "username": "[email protected]",
  "password": "YOUR_PASSWORD",
  "include": [
    "session"
  ]
}

RESPONSE

RESPONSE EXAMPLE

{
  "message": "ok",
  "token": "USER_TOKEN",
  "login_url": "https://example.com/backend/login.php?token=WEB_TOKEN",
  "demo": false,
  "session": {
    "id": "3fcb2ef4-b582-45c4-8677-47dca660611d",
    "token_type": "Bearer",
    "expires_in": 86400,
    "expires_at": "2026-10-23T12:00:00Z",
    "refresh_token": "REFRESH_TOKEN",
    "refresh_expires_at": "2026-11-21T12:00:00Z",
    "session_expires_at": "2027-01-20T12:00:00Z"
  }
}

RESPONSE

RESPONSE EXAMPLE

{
  "code": "MFA_REQUIRED",
  "challenge_id": "CHALLENGE_ID",
  "expires_in": 300
}

Verify sign-in code

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "mfa",
  "challenge_id": "CHALLENGE_ID",
  "otp": "123456"
}

RESPONSE

The same login response shown above. The original include selection is preserved.

Refresh session

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "refresh",
  "refresh_token": "REFRESH_TOKEN"
}

RESPONSE

The same login response, including session and a new refresh token. The previous access-token generation is invalidated. Replay the same Idempotency-Key and body after a timeout; the previous refresh response can be replayed for 24 hours.

Log out

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "logout",
  "refresh_token": "REFRESH_TOKEN"
}

RESPONSE

Empty body. Repeating logout with the same refresh token also returns 204.

ERROR RESPONSES

GET PROFILE

GET https://vt.pageier.com/api/user?action=me

HEADERS

QUERY PARAMETERS

RESPONSE

ERROR RESPONSES

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "permission denied",
    "request_id": "a1b2c3",
    "retryable": false,
    "details": {}
  }
}

GET TOURS

GET https://vt.pageier.com/api/tours

HEADERS

List tours

QUERY PARAMETERS

RESPONSE

RESPONSE EXAMPLE

{
  "message": "ok",
  "data": [
    {
      "id": "41",
      "external": 0,
      "name": "Property tour",
      "date_created": "2026-10-22 12:00:00",
      "author": "Studio",
      "id_user": "7",
      "active": 1,
      "count_rooms": 2,
      "background_image": ""
    }
  ],
  "page": {
    "limit": 25,
    "offset": 0,
    "has_more": false,
    "next_offset": null
  }
}

Tour detail

QUERY PARAMETERS

RESPONSE

Returns the tour and ETag response header. The same fields are returned by tour creation and update.

ERROR RESPONSES

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "permission denied",
    "request_id": "a1b2c3",
    "retryable": false,
    "details": {}
  }
}

ADD / UPDATE TOUR

POST https://vt.pageier.com/api/tours

HEADERS

Create tour

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "create_tour",
  "name": "Property tour",
  "author": "Studio",
  "language": "en_US"
}

RESPONSE

Tour object with the fields documented under GET tours / Tour detail. Owner is derived from the authenticated user.

Update tour

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "update_tour",
  "tour_id": "41",
  "name": "Updated property tour",
  "active": true
}

RESPONSE

Updated tour object and its ETag response header; fields match GET tours / Tour detail.

ERROR RESPONSES

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "permission denied",
    "request_id": "a1b2c3",
    "retryable": false,
    "details": {}
  }
}

DELETE TOUR

DELETE https://vt.pageier.com/api/tours

Permanently deletes the tour, its rooms, navigation links and related records. Removes files that are no longer referenced by another tour or shared library, cancels pending uploads and releases their reservations. Requires capabilities.actions.delete_tour.allowed; permission to delete rooms alone does not grant permission to delete a tour. Tour, room and storage usage are recalculated for the tour owner account. An expired plan does not by itself prevent deletion.

HEADERS

QUERY PARAMETERS

REQUEST EXAMPLE

DELETE /api/tours?tour_id=41 HTTP/1.1
Authorization: Bearer USER_TOKEN
If-Match: "TOUR_ETAG_FROM_DETAIL"

RESPONSE

Empty body after deletion and file cleanup. If the connection times out, repeat the same request as the same user with the original If-Match: a completed deletion returns 204 again without duplicate effects. Idempotency-Key is not required. Active panorama processing returns 409 without deleting the tour. If file cleanup fails after deletion, the response is 503 with error.details.tour_deleted and error.details.cleanup_pending set to true; retry the same DELETE request to complete cleanup. Subsequent API calls also attempt pending cleanup. A deletion takes effect in the viewer as soon as the tour is removed; there is no undo.

ERROR RESPONSES

ERROR RESPONSE EXAMPLE

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "The tour was deleted but file cleanup is pending; retry the same DELETE request",
    "request_id": "a1b2c3",
    "retryable": true,
    "details": {
      "tour_deleted": true,
      "cleanup_pending": true
    }
  }
}

GET ROOMS

GET https://vt.pageier.com/api/rooms

HEADERS

List rooms

QUERY PARAMETERS

RESPONSE

RESPONSE EXAMPLE

{
  "data": [
    {
      "id": "502",
      "tour_id": "41",
      "name": "Living room",
      "type": "image",
      "state": "ready",
      "visible": true,
      "priority": 0,
      "yaw": 35,
      "pitch": 0,
      "northOffset": 90,
      "job_id": "a68027ab-f7b3-46d3-9b6b-d78c8ef476a7",
      "preview_url": "/api/rooms?id_tour=41&action=preview&id_room=502",
      "panorama_url": "/api/rooms?id_tour=41&action=panorama&id_room=502",
      "etag": "\"ROOM_VERSION\""
    }
  ],
  "page": {
    "limit": 25,
    "offset": 0,
    "has_more": false,
    "next_offset": null
  }
}

Room detail

QUERY PARAMETERS

RESPONSE

RESPONSE EXAMPLE

{
  "id": "502",
  "tour_id": "41",
  "name": "Living room",
  "type": "image",
  "state": "ready",
  "visible": true,
  "priority": 0,
  "yaw": 35,
  "pitch": 0,
  "northOffset": 90,
  "job_id": "a68027ab-f7b3-46d3-9b6b-d78c8ef476a7",
  "preview_url": "/api/rooms?id_tour=41&action=preview&id_room=502",
  "panorama_url": "/api/rooms?id_tour=41&action=panorama&id_room=502",
  "etag": "\"ROOM_VERSION\""
}

Upload status

QUERY PARAMETERS

RESPONSE

RESPONSE EXAMPLE

{
  "id": "3fcb2ef4-b582-45c4-8677-47dca660611d",
  "tour_id": "41",
  "state": "initiated",
  "size_bytes": 18350080,
  "received_bytes": 0,
  "part_size_bytes": 2097152,
  "part_count": 9,
  "parts": [],
  "expires_at": "2026-10-23T12:00:00Z",
  "reserved": {
    "rooms": 1,
    "storage_bytes": 18350080,
    "physical_bytes": 1464336384
  },
  "job_id": null,
  "room_id": null,
  "cleanup_pending": false,
  "error": null,
  "target_room_id": null
}

Operation status

QUERY PARAMETERS

RESPONSE

Status reads do not start or resume processing. Subsequent API requests detect abandoned validation, room creation and panorama replacement jobs after the processing timeout plus a 30-second grace period (default: 30 minutes and 30 seconds). Recovery runs only when no processing request or panorama generator holds the upload locks. The job is marked failed with PROCESSING_INTERRUPTED. Cleanup removes temporary files while retaining an already created visible room and its main panorama; for a replacement, it restores the previous panorama. Reservations are released after cleanup succeeds, and retained files and rooms continue to count toward usage. The retained room state becomes ready and the job remains failed. Successful jobs are preserved. Recovery does not resume a failed operation; use a new upload to replace the panorama when needed.

Preview and panorama image

QUERY PARAMETERS

RESPONSE

Send Authorization: Bearer USER_TOKEN. With action=preview, Content-Type is image/jpeg and the body contains the preview image. With action=panorama, Content-Type is image/jpeg or image/png according to the actual file, and the body contains the image stored in viewer/panoramas/. Both require access to the parent tour and a room in that tour. Images are available when the room is ready. Panorama retrieval supports image rooms and local or S3 storage.

ERROR RESPONSES

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "permission denied",
    "request_id": "a1b2c3",
    "retryable": false,
    "details": {}
  }
}

ADD ROOM / UPLOAD

POST https://vt.pageier.com/api/rooms

HEADERS

Start upload

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "initiate_upload",
  "id_tour": "41",
  "filename": "living-room.jpg",
  "media_type": "image/jpeg",
  "size_bytes": 18350080,
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "width": 8192,
  "height": 4096,
  "projection": "equirectangular"
}

RESPONSE

Location points to upload_status. Reserves one room slot for creation or zero slots for replacement, and the reported storage budget on the tour owner account. Replacement needs enough storage for both panoramas until old-file cleanup is complete.

RESPONSE EXAMPLE

{
  "id": "3fcb2ef4-b582-45c4-8677-47dca660611d",
  "tour_id": "41",
  "state": "initiated",
  "size_bytes": 18350080,
  "received_bytes": 0,
  "part_size_bytes": 2097152,
  "part_count": 9,
  "parts": [],
  "expires_at": "2026-10-23T12:00:00Z",
  "reserved": {
    "rooms": 1,
    "storage_bytes": 18350080,
    "physical_bytes": 1464336384
  },
  "job_id": null,
  "room_id": null,
  "cleanup_pending": false,
  "error": null,
  "target_room_id": null
}

Transfer part

MULTIPART FORM PARAMETERS

RESPONSE

Updated upload object, including received parts and checksums; same fields as Start upload. Repeating an identical part is accepted. A different part for the same number returns 409 PART_CONFLICT.

Complete upload

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "complete_upload",
  "id_tour": "41",
  "upload_id": "3fcb2ef4-b582-45c4-8677-47dca660611d",
  "sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
}

RESPONSE

Returns after file validation. The upload state becomes ready. Location contains the operation-status URL.

RESPONSE EXAMPLE

{
  "job_id": "a68027ab-f7b3-46d3-9b6b-d78c8ef476a7",
  "resource_type": "upload",
  "resource_id": "3fcb2ef4-b582-45c4-8677-47dca660611d",
  "state": "succeeded",
  "poll_url": "/api/rooms?id_tour=41&action=job_status&job_id=a68027ab-f7b3-46d3-9b6b-d78c8ef476a7"
}

Create room

BODY PARAMETERS

REQUEST EXAMPLE

{
  "id_tour": "41",
  "name": "Living room",
  "upload_id": "3fcb2ef4-b582-45c4-8677-47dca660611d"
}

RESPONSE

HTTP 201 confirms that the room has been created with visible=true and its main panorama has been saved. The room is immediately included in the viewer, subject to the tour access restrictions. The response contains resource_id (the created room identifier) and job_id and returns after the background processor acknowledges startup, without waiting for compression, derived images or multiresolution. The client can consider creation complete when it receives the room identifier; monitoring the background job is optional. The room state can remain processing while derived images are generated. Errors after acceptance are available through job_status and upload_status. If background processing fails, the created room and main panorama are retained, temporary files and reservations are released after cleanup, and the room state becomes ready while the job reports failed. One reserved room slot becomes consumed and remains in use while the room exists. Repeat the same Idempotency-Key and body after a connection timeout to get the same room and job without starting duplicate processing. A failed background operation is not resumed; replace the panorama with a new upload if processing must be repeated.

RESPONSE EXAMPLE

{
  "job_id": "a68027ab-f7b3-46d3-9b6b-d78c8ef476a7",
  "resource_type": "room",
  "resource_id": "502",
  "state": "pending",
  "poll_url": "/api/rooms?id_tour=41&action=job_status&job_id=a68027ab-f7b3-46d3-9b6b-d78c8ef476a7"
}

Cancel upload

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "cancel_upload",
  "id_tour": "41",
  "upload_id": "3fcb2ef4-b582-45c4-8677-47dca660611d"
}

RESPONSE

Empty body after cleanup. Repeating cancellation of an already cleaned upload returns 204. Reservations are released after file cleanup.

Create navigation link

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "create_room_link",
  "id_tour": "41",
  "source_room_id": "502",
  "target_room_id": "503",
  "yaw": 25,
  "pitch": 0,
  "bidirectional": true,
  "reverse_yaw": -150,
  "reverse_pitch": 0
}

RESPONSE

RESPONSE EXAMPLE

{
  "id": "81",
  "tour_id": "41",
  "source_room_id": "502",
  "target_room_id": "503",
  "reverse_id": "82"
}

ERROR RESPONSES

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "permission denied",
    "request_id": "a1b2c3",
    "retryable": false,
    "details": {}
  }
}

EDIT ROOMS

PUT https://vt.pageier.com/api/rooms

HEADERS

Replace room panorama

First POST rooms with action=initiate_upload and id_room set to the existing room. Transfer parts with action=upload_part and validate with action=complete_upload. Then call this PUT operation with the ready upload. Requires replace_panorama (edit_rooms for an editor), a user Bearer token, the room If-Match and an Idempotency-Key. No additional room slot is consumed. The upload cannot be transferred to a different room or used to create a room.

BODY PARAMETERS

REQUEST EXAMPLE

PUT /api/rooms HTTP/1.1
Authorization: Bearer USER_TOKEN
Content-Type: application/json
If-Match: "ROOM_VERSION_FROM_DETAIL"
Idempotency-Key: replace-room-502-001

{
  "action": "replace_panorama",
  "id_tour": "41",
  "id_room": "502",
  "upload_id": "3fcb2ef4-b582-45c4-8677-47dca660611d"
}

RESPONSE

RESPONSE EXAMPLE

{
  "job_id": "a68027ab-f7b3-46d3-9b6b-d78c8ef476a7",
  "resource_type": "room",
  "resource_id": "502",
  "state": "pending",
  "poll_url": "/api/rooms?id_tour=41&action=job_status&job_id=a68027ab-f7b3-46d3-9b6b-d78c8ef476a7"
}

HTTP 200 confirms that replacement processing was accepted. The response returns after the background processor acknowledges startup, without waiting for panorama processing. Read poll_url until state is succeeded or failed; errors after acceptance are reported by job_status and upload_status. During processing, the room state is processing and it is temporarily excluded from the viewer. The original visibility is restored after success. Room ID, name, initial view, north offset, order, annotations, protections, POIs and navigation links are preserved. Changing the panorama does not move or realign existing hotspots. Read the room again after completion to get its current ETag.

Repeat the same Idempotency-Key, body and original If-Match after a timeout; do not start a separate replacement blindly. A stale version or reused upload is rejected. Permissions, account, plan, storage target and quota are rechecked during processing. If processing fails, the previous panorama and visibility are restored and new files and reservations are cleaned up. Subsequent API requests mark abandoned processing as failed and restore the previous panorama once the processing deadline has passed and no panorama generator is still active. After failure and cleanup, initiate a new upload.

Old files are removed only after successful processing and only when no other room, alternate panorama or language panorama references them. If old-file cleanup fails, replacement remains successful; upload/job status reports cleanup_pending=true and subsequent API requests retry cleanup. Old storage remains reserved until cleanup completes. Both original files must fit the available storage during replacement, including when the room count limit has been reached.

Rename room, set initial position and compass north

BODY PARAMETERS

Supply at least one of name, yaw, pitch or northOffset. Omitted fields keep their current values; null and boolean values are not accepted for these fields. The initial position controls the view when entering this room. Changing yaw or pitch also invokes the tour loading-background generator when applicable. North can be changed independently. These updates do not consume a room slot or upload reservation.

REQUEST EXAMPLE

{
  "id_tour": "41",
  "id_room": "502",
  "yaw": 35,
  "pitch": 0,
  "northOffset": 90
}

To rename only, send id_tour, id_room and name. To change only north, send id_tour, id_room and northOffset.

RESPONSE

Updated room with the saved yaw, pitch and northOffset values, and its ETag response header. If-Match must contain the room ETag. After a timeout, read the room again to check the saved values before retrying with its current ETag. A stale If-Match returns 412 without applying changes.

Set room order and initial room

BODY PARAMETERS

REQUEST EXAMPLE

{
  "action": "set_order",
  "id_tour": "41",
  "room_ids": [
    "502",
    "503"
  ],
  "initial_room_id": "502"
}

RESPONSE

Updated tour object and ETag response header; fields match GET tours / Tour detail. If-Match must contain the tour ETag.

ERROR RESPONSES

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "permission denied",
    "request_id": "a1b2c3",
    "retryable": false,
    "details": {}
  }
}

DELETE ROOM

DELETE https://vt.pageier.com/api/rooms

HEADERS

QUERY PARAMETERS

RESPONSE

Empty body after deletion and cleanup. The upload-to-room association is released while the upload record and deletion receipt are retained. A repeated request with the same original If-Match returns 204 after authorization checks, including when the numerical room ID has since been reused. To delete a room currently using that ID, read its current ETag and send that value. Old cleanup and deletion operations cannot modify a different room that reuses the identifier.

ERROR RESPONSES

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "permission denied",
    "request_id": "a1b2c3",
    "retryable": false,
    "details": {}
  }
}