# OpenAPI

Connect your server to Team VR data and reconstruction APIs with Developer app credentials.

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

Realsee **OpenAPI** connects your server to spatial data and workflows, including VR data, interactions, Live, and Argus. Create or select a **Developer app** owned by your Team, then use its AK and SK to obtain a gateway access token.

[Run the Team API starter](https://developer.realsee.ai/docs/open-api/quickstart) for a complete local project, a copyable AI coding prompt, and token → VR list → authorized Work → Five SDK rendering. Start with its public Demo before adding credentials locally.

## Start with an app

[Open Apps](https://developer.realsee.ai/dashboard/apps), select the owning Team, and choose an enabled Developer app. Obtain its AK and SK from the app's details. See [Team and App Management](https://developer.realsee.ai/docs/team-app-management) for app creation, ownership, and availability.

## Base URL and authentication

The overseas gateway is:

```text
https://app-gateway.realsee.ai
```

Exchange AK and SK server-side using `POST /auth/access_token` with form fields `app_key` and `app_secret`. The token response includes `data.access_token` and `data.expire_at`, a Unix timestamp in seconds. Keep the token on your server and obtain another when needed according to its returned expiry.

Authenticated `/open` requests send the raw token value in the `Authorization` header, without a `Bearer` prefix. The [endpoint guide](https://developer.realsee.ai/docs/open-api/reference) shows the exchange and request prerequisites. [Authentication](https://developer.realsee.ai/docs/authentication) explains how to obtain and protect app credentials and access tokens.

Never place SK or access tokens in browser bundles, URLs, logs, analytics, or support messages. Your backend must authorize its own users and return only the data those users may see.

## Choose the operation

Use the [API Reference](https://developer.realsee.ai/api-reference) for endpoint methods, parameters, and response schemas.

- **VR and scene data:** discover resources available to the Team and fetch the selected resource using its documented identifier.
- **Interactions and presentation:** use the documented hotspot, ruler, floorplan, and related data APIs needed by your SDK experience.
- **Live:** follow the [Live guide](https://developer.realsee.ai/docs/live) for room, ticket, connection, and optional voice requirements.
- **Argus:** follow the [Argus guide](https://developer.realsee.ai/docs/argus) for upload, task creation, polling, and output contracts.
- **Pano-to-VR:** follow the [Pano-to-VR guide](https://developer.realsee.ai/docs/pano-to-vr) to turn panoramas into a SaaS VR project.

Some operations change data or create tasks. Check the endpoint's behavior before executing it. An arbitrary metadata response is not automatically Five SDK Work data. Use a Work payload and `parseWork` for the [Five SDK integration](https://developer.realsee.ai/docs/five-sdk/quickstart).

## Interpret the actual result

Inspect both the HTTP result and the endpoint's business response fields. The gateway contracts use fields such as `code`, `status`, and `business_code`; their meaning and response data are defined per endpoint. Do not assume every business error uses the same numeric value as an HTTP status.

Handle invalid or expired credentials, a disabled app, inaccessible or missing resources, invalid input, and rate limiting according to the endpoint's response. An empty resource list is a valid result when the Team has no matching VRs. [Ask in the Realsee Discord community](https://discord.gg/JvxBZJkbNZ) for help investigating integration errors.

## Next steps

- [Endpoint guide](https://developer.realsee.ai/docs/open-api/reference) — token exchange, Team resources, and selected Work.
- [API Reference](https://developer.realsee.ai/api-reference) — complete endpoint contracts.
- [Get Started](https://developer.realsee.ai/docs/get-started) — credentials, first integration, and the independent public Demo.