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

Upload a file

Client or secret key.

Uploads a file as multipart/form-data. Which key may upload it, and what is created, depends on asset_type:

asset_typeKeysLargest fileMIME typesCreates
anchor-featuresClient or secret50 MBapplication/octet-stream, application/jsonAn anchor file, free of the storage quota
meshClient or secret50 MBapplication/octet-stream (a .rvca world-mesh snapshot)An anchor file, free of the storage quota
imageSecret only10 MBimage/jpeg, image/png, image/gif, image/webpA file record, counted against the storage quota
videoSecret only100 MBvideo/mp4, video/webm, video/quicktimeA file record, counted against the storage quota
3d-modelSecret only50 MBmodel/gltf-binary, model/gltf+json, application/octet-streamA file record, counted against the storage quota

Without asset_type the upload is an image, so a client key must name anchor-features or mesh; any other type answers 403 API_KEY_TYPE_NOT_ALLOWED. The MIME type is the file part's own Content-Type. When that is application/octet-stream and the asset_type does not accept it (image and video), the type is taken from the file name's extension instead: .jpg or .jpeg, .png, .gif, .webp, .mp4, .webm or .mov.

An anchor file's response gives a url to pass to a cloud or geospatial anchor as descriptors_url, feature_points_url or mesh_url. It is deleted with the anchor that references it, and after 24 hours if no anchor does. A file record's response gives an id to attach or link as user_asset_id; it is deleted 90 days after upload.

With a client key, project_id must be the key's project. Uploads are not counted against the monthly API request quota.

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

The file.

uuid
required

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

string
enum
Defaults to image

Default image. See the table above.

Allowed:
string
length ≤ 255

File records only: your app's id for the user who uploaded it. Up to 255 characters.

string

File records only: cut to 250 characters. Default: the file's name.

string

File records only: cut to 2000 characters.

string

Name to use when the file part has none.

Responses

INVALID_CONTENT_TYPE: the body is not multipart/form-data.

INVALID_FORM_DATA: the form could not be read.

MISSING_FILE: no file part.

MISSING_PROJECT_ID: no project_id.

INVALID_ASSET_TYPE: asset_type is not one of the five types.

FILE_TOO_LARGE: the file is over the type's limit.

INVALID_FILE_TYPE: the file part's MIME type is not allowed for the type.

APP_USER_ID_TOO_LONG: app_user_id is over 255 characters.

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.

API_KEY_TYPE_NOT_ALLOWED: a client key uploading an image, video or 3d-model, or sending no asset_type.

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.

STORAGE_LIMIT_REACHED: an image, video or 3d-model upload with the team's storage quota used up.

RATE_LIMITED: for anchor-features and mesh, 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.

UPLOAD_FAILED: the file could not be stored.

ASSET_CREATE_FAILED: the file record could not be created.

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.

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