# Team API Quickstart

Connect the official local starter to a Team-owned Developer app, read its VR list, and render an authorized scene.

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

## Run the complete starter

Use the fixed **1.3.0** release.

- [Agent instructions](https://developer.realsee.ai/starters/react-five/1.3.0/agent.md)
- [Release manifest and SHA-256](https://developer.realsee.ai/starters/react-five/1.3.0/manifest.json)
- [Complete project ZIP](https://developer.realsee.ai/starters/react-five/1.3.0/starter.zip)
- [Public Demo guide](https://developer.realsee.ai/starters/react-five/1.3.0/demo.md)
- [Team integration guide](https://developer.realsee.ai/starters/react-five/1.3.0/team.md)

Use Node 24. Read the manifest, download its archive, and verify the SHA-256 before extracting into a new directory. Preserve the lockfile and pinned dependencies. From `realsee-react-five`, run:

```bash
npm ci
npm run check
npm run build
npm run dev
```

Open the actual local URL printed by the server. Verify that the public scene reaches Ready. Switch the viewer from Panorama to Floorplan and back, then use Reset view. No account or credentials are required for Public Demo. Report browser checks only when actually performed.

For Team data, run `npm run configure -- --device`. Give the user its verification URL and eight-character code, keep the command running, and wait while they sign in, select their Team and app, and authorize. Do not approve for the user. The helper writes the local `.env` and preserves existing credentials. If authorization is unavailable, create `.env` from `.env.example` only if absent and let the user fill AK, SK and Team source locally. Never paste secrets into chat or expose them to browser code. Restart the server, select Your Team, and click Check API & list VRs. Check token exchange, the authorized VR list, and selected Work separately. Public Demo success does not prove Team API access; an empty authorized list is a distinct successful read.


Use the same React + TypeScript project as the [public Five SDK Quickstart](https://developer.realsee.ai/docs/five-sdk/quickstart). First get the public scene running, then connect the local Node backend to your Team's real data. You do not need another app for each product capability.

## Prepare your Developer app

[Open Apps](https://developer.realsee.ai/dashboard/apps), select the owning Team, and use an existing enabled **Developer app**. A Team owner can create one when the Team has capacity. An expired or disabled app still counts toward the 10-app limit.

You will choose this Team and app when authorizing your coding tool. Keep credentials out of AI chats and community messages.

## Start the project

Use [fixed starter instructions](https://developer.realsee.ai/starters/react-five/1.3.0/agent.md), or download the project and follow [its release manifest](https://developer.realsee.ai/starters/react-five/manifest.json). In the extracted project run:

```bash
npm ci
npm run check
npm run build
npm run dev
```

Verify the Public Demo first. It must not be presented as proof that your Team credentials work.

## Configure the local backend

Run the initialization helper in the extracted project:

```bash
npm run configure -- --device
```

Open the verification URL it prints and check the eight-character code. **Sign in, choose the owning Team, then select your app** and choose **Authorize agent**. Keep the command running; it writes the selected app's configuration to `.env` without printing credentials. Existing nonempty credentials are preserved. The code expires after ten minutes and can deliver configuration once.

The [device authorization page](https://developer.realsee.ai/agent/setup) also accepts the code manually.

### Manual configuration

If `.env` does not already exist, copy `.env.example` to `.env` next to the starter's `package.json`. Keep an existing `.env` and update only the values needed for this integration. Fill these values yourself on your computer. Do not paste SK or tokens into an AI chat, browser code, URLs, screenshots, or logs.

```dotenv
REALSEE_APP_KEY=YOUR_APP_AK
REALSEE_APP_SECRET=YOUR_APP_SK
REALSEE_TEAM_SOURCE=YOUR_OWNING_TEAM_SOURCE
REALSEE_GATEWAY_BASE_URL=https://app-gateway.realsee.ai
```

After changing the environment file, stop the running development process with Ctrl+C and run `npm run dev` again. Open the local URL it prints, select **Your Team**, then click **Check API & list VRs**. Switching to the Team tab does not start the API check automatically. The backend reads the environment; the browser never receives SK or access tokens.

## Check the token and VR list

The starter uses the pinned `@realsee/api` client from its server and implements this read-only sequence:

1. Exchange AK/SK using `POST /auth/access_token`, with form fields `app_key` and `app_secret`.
2. Check the HTTP response and business `code`; use `data.access_token` and its returned `data.expire_at`.
3. Call `POST /open/v3/custom/search` with JSON `source`, `page`, and `page_size`. The Authorization header contains the raw token, without a `Bearer` prefix.
4. Display the returned VR list and its pagination.

An authorized empty list means no visible VR was returned. Report **API connected, no VRs available**. It does not require creating another app, and it does not prove a real Team scene rendered.

When VRs are available, the local app shows **Team VRs** and the current page. Use **Next** and **Previous** to browse the directory.

## Select and render your VR

Click a VR in the returned **Team VRs** directory and wait for **Ready** in the viewer. The local backend binds that choice to the configured Team and obtains Work through `GET /open/v3/vr/info?resource_code=...` before returning the renderable payload to Five SDK.

The [published Work endpoint](https://api-docs.realsee.dev/vr-basic-data-309898715e0.md) returns the renderable payload in `data`. The starter parses it with `@realsee/five@6.9.2`. Resource availability and asset access still depend on your app, Team, and returned Work. A generic metadata object must not be treated as a rendered scene.

The starter loads this payload using its shared viewer. Only report **Team scene ready** after the selected scene has loaded. If Work or its assets fail, keep the failure visible; do not silently replace the result with Public Demo data.

Directory selections expire after **five minutes** and after a server restart. If a selection expires, click **Refresh Team directory**, then select the VR again.

## Understand a failure

| Result | Meaning and action |
| --- | --- |
| Configuration missing | Run device authorization or fill the named variables locally, then restart the server. Public Demo remains available. |
| Token failed | Check the app, credentials, and selected gateway. HTTP 200 alone is not success. |
| Resource request failed | Check Team source, app availability, and the API business result. |
| No VRs | The read succeeded but returned no visible resources. Use Public Demo or prepare an accessible VR. |
| Selection expired | Reload the list and select the VR again. |
| Work or assets failed | Check the selected VR and network. API success and scene success remain separate. |

## Continue building

- [Endpoint Reference](https://developer.realsee.ai/docs/open-api/reference) and the [complete API Reference](https://developer.realsee.ai/api-reference) define the requests and responses.
- [Authentication](https://developer.realsee.ai/docs/authentication) explains how to keep app credentials and access tokens on your server.
- [Team and App Management](https://developer.realsee.ai/docs/team-app-management) covers app ownership, limits, and continued use.
- [Five SDK](https://developer.realsee.ai/docs/five-sdk) explains rendering and interaction.