Hire a ReactVision Expert 🛠️Launch Studio 🖥️Sponsor on GitHub ❤️
HomeGuidesAPI ReferenceChangelogDiscussions
Hire a ReactVision Expert 🛠️Launch Studio 🖥️Sponsor on GitHub ❤️Log In
API Reference

Create a cloud anchor

post
https://platform.reactvision.xyz/functions/v1/cloud-anchors/create

Client or secret key.

Creates a cloud anchor from the visual features a device captured. Upload the descriptors first with POST /assets/upload and asset_type=anchor-features, then pass the returned url as descriptors_url.

With a client key, project_id must be the key's project, and is_public must be true or left out: a client key cannot read a private anchor back, so it cannot create one.

The response is the whole anchor, including keypoints_json and associations_json, which the read operations never return.

Counts as one request against the team's monthly API request quota, including a request that then fails a check.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
uuid
required

The project the anchor belongs to. With a client key the project must be the key's own project.

number
required

Camera focal length X, in pixels.

number
required

Camera focal length Y, in pixels.

number
required

Camera principal point X, usually image_width / 2.

number
required

Camera principal point Y, usually image_height / 2.

integer
required

Source image width, in pixels.

integer
required

Source image height, in pixels.

string
required

Binary feature descriptors, uploaded with asset_type=anchor-features. Must be the url that POST /assets/upload returned for this project's file.

keypoints_json
array of objects
required
length between 1 and 8192

1 to 8192 keypoints, at most 512 KB as JSON. At least 50 well-spread keypoints are recommended for reliable resolving.

keypoints_json*

One detected visual feature. Properties beyond these are accepted.

number
required

X coordinate, in the capture SDK's own units; may be negative.

number
required

Y coordinate, in the same units; may be negative.

number
required

Feature diameter, in the same units.

number

Orientation in degrees, 0 to 360.

number

Detector response strength, 0 to 1.

integer

Scale-space octave the feature was detected in.

integer

Feature classifier id.

integer
required

Number of feature descriptors.

integer
required

Must equal the length of keypoints_json.

string
length ≤ 150

Up to 150 characters.

string
length ≤ 2000

Up to 2000 characters.

string
length ≤ 255

Your app's id for the user who hosted the anchor. Up to 255 characters.

external_user_metadata
object

Your data about that user, up to 4096 bytes as JSON.

number
-90 to 90

-90 to 90. Send it with longitude to make the anchor findable by nearby searches.

number
-180 to 180

-180 to 180.

number

Altitude, in meters.

number

Local position X. Default 0.

number

Local position Y. Default 0.

number

Local position Z. Default 0.

number

Quaternion X. Default 0.

number

Quaternion Y. Default 0.

number

Quaternion Z. Default 0.

number

Quaternion W. Default 1.

tags
array of strings

Default [].

tags
metadata
object

Up to 4096 bytes as JSON. Default {}.

string
enum

Platform that hosted the anchor.

Allowed:
string
length ≤ 120

Up to 120 characters.

string
length ≤ 40

Up to 40 characters.

string

Feature points file, uploaded with asset_type=anchor-features. Must be the url that POST /assets/upload returned for this project's file.

string

Captured world-mesh snapshot (.rvca), uploaded with asset_type=mesh. Must be the url that POST /assets/upload returned for this project's file.

string

Feature-to-point associations, any JSON.

integer

Default 0.

string
length ≤ 32

Up to 32 characters. Default ORB.

integer

Descriptor size in bytes. Default 32.

boolean

Default true. false makes the anchor private: reachable only with a secret key or a Studio session. A client key must send true or leave it out, since it could not read a private anchor back.

Responses

INVALID_BODY: the body is not valid JSON, or not a JSON object.

MISSING_FIELD: a required field is missing; the message names the first one.

INVALID_KEYPOINTS: keypoints_json is not an array of 1 to 8192 keypoints with numeric x, y and size, or is over 512 KB.

KEYPOINT_COUNT_MISMATCH: keypoint_count is not the length of keypoints_json.

INVALID_FIELD_VALUE: a text field is not a string, metadata or external_user_metadata is not an object, or a client key sent an is_public other than true.

FIELD_TOO_LONG: a text field is over its limit, or a JSON object is over 4096 bytes.

INVALID_PLATFORM: platform is not ios, android or web.

INVALID_LATITUDE: latitude is outside -90 to 90.

INVALID_LONGITUDE: longitude is outside -180 to 180.

INVALID_DESCRIPTORS_URL: descriptors_url is not an anchor file this project uploaded.

INVALID_FEATURE_POINTS_URL: feature_points_url is not an anchor file this project uploaded.

INVALID_MESH_URL: mesh_url is not a mesh file this project uploaded.

MISSING_API_KEY: no x-api-key header.

INVALID_API_KEY_FORMAT: the key is not rv_live_, rv_client_ or rv_secret_ followed by 64 lowercase hexadecimal characters.

INVALID_API_KEY: no such key, or a key sent with the wrong prefix for its type.

API_KEY_EXPIRED: the key is past its expiry date.

AUTH_ERROR: a user token (rv_ut_) was sent as a Bearer token. This operation does not accept user tokens.

PROJECT_NOT_FOUND: project_id does not exist, belongs to another team, or is not the project the key is bound to. The three answers are the same.

API_REQUEST_LIMIT_REACHED: the team's monthly API request quota is used up.

RATE_LIMITED: more than 30 a minute from one IP address for your team; or, for a secret key, more than 1,200 requests a minute across all operations. Wait the number of seconds in Retry-After. See Limits.

CREATE_FAILED: the anchor could not be stored, for example because a numeric field had the wrong type.

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

API_KEY_LOOKUP_FAILED: the key could not be checked. Retry; this does not mean the key is invalid.

PROJECT_LOOKUP_FAILED: the project could not be checked. Retry.

Updated about 11 hours ago

Language
Credentials
Header
LoadingLoading…
Response
Choose an example:
application/json

Updated about 11 hours ago