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

Endpoint Reference

Exchange app credentials for a token, list authorized Team resources, and retrieve selected Work.

View Markdown
On this page

Start with token exchange, list your Team's resources, then read the selected resource. Use the API Reference for complete methods, parameters, and response schemas.

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 successful response contains data.access_token and data.expire_at (a Unix timestamp in seconds), alongside the gateway business result fields. Check the business result before using the token; an HTTP 200 alone does not mean authentication succeeded. 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 empty resource list is a valid result when the Team has no matching VRs. Check the business result before reading data.list; distinguish an empty list from a token or authorization failure. 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.

Use the Five SDK Work payload returned in data by GET /open/v3/vr/info. After authorizing a resource selected from the owning Team's list, obtain its Work and load it with await five.load(parseWork(workJSON)). Follow the Team API starter for backend, environment, and viewer setup. The VR directory response is not Work data and cannot be passed directly to Five SDK.

Use Live for room operations, Argus for reconstruction output packages, and Pano-to-VR for SaaS VR generation. Each operation has its own input and result fields.

Errors and continued use

Check both the HTTP status and the endpoint's code, status, and other business result fields. Handle token expiry, app availability, resource access, rate limiting, and task failure separately.

Use the Realsee Discord community for integration questions and continued-access support.

See also