Create a scan

post

https://platform.reactvision.xyz/functions/v1/vps/scans

Secret key only. Scope: vps.

Also accepts a user token.

Creates a scan, awaiting_upload, of a known location (location_id) or of a new place (location), which it creates in the same call; a refused scan leaves no location behind. Then upload the recording with POST /vps/scans/{scan_id}/upload. Viro's uploadScanRecording() makes every call of a scan.

A scan is a recording from Viro's AR recorder (session.jsonl and video.mp4), zipped.

With x-app-user-id, or a user token, the scan belongs to that app user, who can scan only its own locations: a shared one answers 403 VPS_SHARED_LOCATION. The app user's scans count toward a daily limit of 10, unless the team set its own in the Editor.

Needs a paid plan. Processing is billed as compute time, only when the map is accepted. Not counted against the monthly API request quota.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Send location_id to scan a known location, or location to scan a new place.

location_id

uuid

The location to scan.

location

object

outputs

array of strings

What to build besides the map, which is always built. semantic needs mesh. Default ["mesh"].

outputs

Allowed:

mesh_quality

string

enum

How detailed the mesh is. low is quickest and builds no HD mesh; high uses full-resolution depth, a denser HD mesh and twice the texture resolution, and takes about 1.75 times as long to process, which is billed as compute. Default medium.

Allowed:

keep_recording

boolean

Default false: the recording is kept only while it is processed, never counts toward the storage quota, and the scan is never part of a merge. true keeps it, which a merge of the location's scans needs.

Headers

x-project-id

uuid

required

The project. With a client key or a bound secret key, the key's own project; with a user token, the token's project.

x-app-user-id

string

length between 1 and 255

Your id for the signed-in app user: 1 to 255 printable ASCII characters, no spaces, not . or ... With a secret key, the request acts for that app user: it sees the app user's locations and scans and the shared ones, and changes only the app user's own. With a user token, leave it out or send the token's own app user; another one answers 403 APP_USER_MISMATCH. A client or legacy key cannot send it (403 APP_USER_ID_NOT_ALLOWED).

Responses

Create a scan

`awaiting_upload`.

`NOT_FOUND`: `location_id` is no location the request can see.

`TOO_LARGE`: the JSON body is over 64 KB.

`RATE_LIMITED`: for a secret key, more than 1,200 requests a minute across all operations. Wait the number of seconds in `Retry-After`. See Limits.

`VPS_USER_LIMIT_REACHED`: the app user has started as many scans today (UTC) as the team allows.

`INTERNAL_ERROR`: an unexpected error. Retry, and quote `meta.request_id` to support if it persists.

`AUTH_UNAVAILABLE`: the key or user token could not be checked. Retry; this does not mean it is invalid.

`VPS_LOOKUP_FAILED`: the records could not be read or written. Retry.

`COMPUTE_BILLING_UNAVAILABLE`: the team's billing could not be checked. Retry.

201The scan, awaiting_upload.

404NOT_FOUND: location_id is no location the request can see.

413TOO_LARGE: the JSON body is over 64 KB.

429RATE_LIMITED: for a secret key, more than 1,200 requests a minute across all operations. Wait the number of seconds in Retry-After. See Limits. VPS_USER_LIMIT_REACHED: the app user has started as many scans today (UTC) as the team allows.