Endpoint Reference | Realsee Developer Platform

This page is the per-endpoint reference for Realsee OpenAPI. Each section documents one path: method, reviewed capability, request shape, response shape, and an executable command-line example.

All endpoints share the same conventions:

Base URL. https://app-gateway.realsee.ai
Authentication. Authorization: YOUR_ACCESS_TOKEN on every call. See Authentication for the token exchange.
Response envelope. { code, msg, data }. Inspect code even when HTTP status is 200. See the OpenAPI overview for the error table.

The full catalog is browsable in the API Reference on the developer portal. The examples below document the most common read path for bootstrapping Five SDK and interaction data.

Tour Read

GET /open/work/show.json

Show published tour — read browser-safe published tour presentation data.

Capability

This endpoint requires the Tour Read capability. Include the need in your App request before calling it in production.

Field	Value
Method	`GET`
Path	`/open/work/show.json`
Tags	Tour Read
Scope	Tour Read

Request parameters

Pass the tour identifier as a query parameter. The gateway resolves it against the apps your token is bound to and returns 403 if the work isn't visible.

Parameter	In	Type	Required	Description
`work_code`	query	`string`	Yes	Realsee work identifier (e.g. `81RojBlJQdVTglNNMr`).

Example request

curl -X GET "https://app-gateway.realsee.ai/open/work/show.json?work_code=81RojBlJQdVTglNNMr" \
  -H "Authorization: $REALSEE_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "work_code": "81RojBlJQdVTglNNMr",
    "title": "Showroom — Beijing flagship",
    "cover_image": "https://app-gateway.realsee.ai/open/work/asset/81RojBlJQdVTglNNMr/cover.jpg",
    "published_at": "2026-04-12T08:14:00Z",
    "share_url": "https://realsee.com/v/81RojBlJQdVTglNNMr",
    "panorama_count": 24,
    "default_panorama_index": 0,
    "geometry_url": "https://app-gateway.realsee.ai/open/work/asset/81RojBlJQdVTglNNMr/geometry.bin"
  }
}

The data payload is the published-tour presentation envelope — it is safe to ship to browser clients. It excludes capture-time fields (raw point clouds, internal IDs, draft state) that live behind higher-scope endpoints.

---

POST /open/v1/work/detail.json

Read open-work detail — metadata needed to initialize a Five SDK open-work experience.

Capability

This endpoint requires the Tour Read capability. Include the need in your App request before calling it in production.

Field	Value
Method	`POST`
Path	`/open/v1/work/detail.json`
Tags	Tour Read
Scope	Tour Read

This endpoint is the canonical bootstrap call for Five SDK integrations. Fetch the response server-side, embed the payload in your initial HTML, parse it with parseWork, and load it with five.load(parseWork(workJSON)).

Request body

{
  "work_code": "81RojBlJQdVTglNNMr",
  "include_geometry": true,
  "include_panoramas": true
}

Field	Type	Required	Description
`work_code`	`string`	Yes	Realsee work identifier.
`include_geometry`	`boolean`	No	Include geometry references in the response. Defaults to `true`. Set `false` for panorama-only flows.
`include_panoramas`	`boolean`	No	Include the panorama list. Defaults to `true`.

Example request

curl -X POST "https://app-gateway.realsee.ai/open/v1/work/detail.json" \
  -H "Authorization: $REALSEE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "work_code": "81RojBlJQdVTglNNMr" }'

Example response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "work_code": "81RojBlJQdVTglNNMr",
    "version": "5.0",
    "panoramas": [
      {
        "index": 0,
        "position": [0.12, 1.55, -2.34],
        "image_url": "https://app-gateway.realsee.ai/open/work/asset/81RojBlJQdVTglNNMr/pano_0.jpg",
        "tile_template": "https://app-gateway.realsee.ai/open/work/asset/81RojBlJQdVTglNNMr/pano_0/{level}/{x}_{y}.jpg"
      }
    ],
    "geometry": {
      "mesh_url": "https://app-gateway.realsee.ai/open/work/asset/81RojBlJQdVTglNNMr/mesh.glb",
      "texture_url": "https://app-gateway.realsee.ai/open/work/asset/81RojBlJQdVTglNNMr/texture.jpg"
    },
    "default_mode": "panorama",
    "default_panorama_index": 0
  }
}

Pass the data object through parseWork(data) before loading it with five.load().

---

Interaction Read

List tour tags — read approved tag and interaction metadata for SDK experiences.

Capability

This endpoint requires the Interaction Read capability. Include the need in your App request before calling it in production.

Field	Value
Method	`GET`
Path	`/open/work/tag/list.json`
Tags	Interaction Read
Scope	Interaction Read

Tags are the user-visible annotations layered on a tour — hotspots, callouts, "next room" arrows. The list returned here matches what end users see in the public viewer; use it to render the same annotations inside your own Five SDK integration.

Request parameters

Parameter	In	Type	Required	Description
`work_code`	query	`string`	Yes	Realsee work identifier.
`lang`	query	`string`	No	BCP-47 language tag for localized tag content (e.g. `en`, `zh-CN`). Defaults to the tour's primary language.

Example request

curl -X GET "https://app-gateway.realsee.ai/open/work/tag/list.json?work_code=81RojBlJQdVTglNNMr&lang=en" \
  -H "Authorization: $REALSEE_ACCESS_TOKEN" \
  -H "Accept: application/json"

Example response

{
  "code": 0,
  "msg": "ok",
  "data": {
    "work_code": "81RojBlJQdVTglNNMr",
    "tags": [
      {
        "tag_id": "tag_001",
        "type": "hotspot",
        "title": "Reception desk",
        "description": "Front-of-house concierge — staffed 09:00 – 21:00.",
        "position": [1.20, 1.45, -3.10],
        "panorama_index": 0,
        "icon": "info"
      },
      {
        "tag_id": "tag_002",
        "type": "link",
        "title": "Brochure",
        "description": null,
        "position": [2.50, 1.55, -1.80],
        "panorama_index": 1,
        "icon": "document",
        "url": "https://app-gateway.realsee.ai/open/work/asset/81RojBlJQdVTglNNMr/brochure.pdf"
      }
    ],
    "total": 2
  }
}

Tag positions are in the same world-space coordinates Five SDK uses, so you can pass them through to plugin APIs without conversion.

---

Tour Read

GET /open/work/show.json

Request parameters

Example request

Example response

POST /open/v1/work/detail.json

Request body

Example request

Example response

Interaction Read

GET /open/work/tag/list.json

Request parameters

Example request

Example response

See also