Skip to main content
Realsee
Documentation
  1. Docs
  2. OpenAPI
  3. Endpoint Reference

Endpoint Reference

Verified gateway authentication, Team resource discovery, and links to complete endpoint contracts.

Use the published API Reference for the complete methods, parameters, and response schemas. The gateway routes below are recorded in the portal's OpenAPI inventory and show how to start with authenticated Team data. They do not create separate capability groups or application steps: a Developer app uses the shared /open interface scope.

Exchange app credentials

POST https://app-gateway.realsee.ai/auth/access_token

Send the AK and SK as form fields from your backend:

curl --request POST 'https://app-gateway.realsee.ai/auth/access_token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode "app_key=$REALSEE_APP_KEY" \
  --data-urlencode "app_secret=$REALSEE_APP_SECRET"

The documented successful response contains data.access_token and data.expire_at (a Unix timestamp in seconds), alongside the gateway business result fields. Check the actual response before using it; do not treat an HTTP 200 alone as authentication success. Cache tokens server-side according to their returned expiry, and keep AK/SK/token values out of logs and browser code.

For the following /open calls, send Authorization: YOUR_ACCESS_TOKEN with the raw token value, without a Bearer prefix.

Discover Team resources

POST https://app-gateway.realsee.ai/open/v3/custom/search

This is a read-only resource list operation despite its HTTP POST method. Its JSON request uses the owning Team's source, page, and page_size. Use the Team you are authorized to access; do not substitute a UserCode or an app's AK for the Team source.

curl --request POST 'https://app-gateway.realsee.ai/open/v3/custom/search' \
  --header "Authorization: $REALSEE_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data "{\"source\":\"$REALSEE_TEAM_SOURCE\",\"page\":1,\"page_size\":10}"

The list response uses data.list, with pagination fields page, page_size, total, and total_pages. Returned list items can provide name, resource_code, and picture_url; use the endpoint schema and actual response for field availability.

An authenticated request may return no matching resources. That is different from a token or authorization failure, and it does not require creating another app. Use the documented response schema to inspect the business result and list. The public Five Demo remains available when the Team has no suitable VR.

Read a selected resource

MethodPathPurpose and prerequisites
GET/open/v3/vr/infoRead VR basic data; requires resource_code and the access-token header.
GET/open/v3/hot/listRead hotspot data according to the endpoint's resource parameters.
GET/open/v3/floorplan/pluginsRead floorplan plugin data according to its documented resource parameters.

Use a resource identifier from authorized Team data, validate access in your own backend, and follow the individual API Reference schema. A resource identifier supplied by your frontend is not, by itself, proof of authorization. Do not assume a returned JSON object is browser-safe or valid Five SDK Work merely because it came from a read endpoint.

When your integration has obtained a documented Five SDK Work payload named workJSON, append the viewer to its container and load it with await five.load(parseWork(workJSON)). The VR directory and arbitrary metadata responses must not be passed to this call as if they were Work data.

Live room and Argus reconstruction operations have different inputs and effects from these reads. Their documentation groups describe functionality, not separate portal approval. Use Live, Argus, and Panorama to VR for those concrete contracts.

Errors and continued use

Preserve the distinction between HTTP failure and endpoint business failure. Follow the documented code, status, and other result fields; token expiry, app availability, resource access, rate limiting, and task failure are different conditions. There is no universal “apply for this capability” remedy.

The App request remains Completed after a later API error or trial expiry. Discuss production or continued use in the Realsee Discord community. Trial extensions require confirmation from the team; continue with your existing app.

See also