# Endpoint Reference

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

Canonical: https://developer.realsee.ai/docs/open-api/reference
Source: https://developer.realsee.ai/docs/open-api/reference.md
Language: en

Start with token exchange, list your Team's resources, then read the selected resource. Use the [API Reference](https://developer.realsee.ai/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:

```bash
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.

```bash
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

| Method | Path | Purpose and prerequisites |
| --- | --- | --- |
| `GET` | `/open/v3/vr/info` | Read VR basic data; requires `resource_code` and the access-token header. |
| `GET` | `/open/v3/hot/list` | Read hotspot data according to the endpoint's resource parameters. |
| `GET` | `/open/v3/floorplan/plugins` | Read 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](https://developer.realsee.ai/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](https://developer.realsee.ai/docs/open-api/quickstart) for backend, environment, and viewer setup. The VR directory response is not Work data and cannot be passed directly to Five SDK.

Use [Live](https://developer.realsee.ai/docs/live) for room operations, [Argus](https://developer.realsee.ai/docs/argus) for reconstruction output packages, and [Pano-to-VR](https://developer.realsee.ai/docs/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](https://discord.gg/JvxBZJkbNZ) for integration questions and continued-access support.

## See also

- [OpenAPI overview](https://developer.realsee.ai/docs/open-api) — server integration and available operations.
- [Authentication](https://developer.realsee.ai/docs/authentication) — app credentials, access tokens, and server-side security.
- [Team and App Management](https://developer.realsee.ai/docs/team-app-management) — app creation, ownership, and availability.
- [Five SDK Quickstart](https://developer.realsee.ai/docs/five-sdk/quickstart) — rendering a valid Work payload.