# mnrvAR

> mnrvAR is a no-code WebAR platform. With an API key you can create, publish and measure augmented reality experiences over HTTP, with no browser or editor for the templates listed below.

The API is served at https://mnrvar.com/api/v1. It is JSON over HTTPS and authenticated with an API key that the account owner creates in Settings, API keys. API keys need a paid plan.

## Docs

- [API quickstart](https://mnrvar.com/docs/api.md): A complete worked session, the error table, limits and what needs the visual editor. Raw markdown.
- [API quickstart, web page](https://mnrvar.com/docs/api): The same content rendered as a page.
- [OpenAPI document](https://mnrvar.com/api/v1/openapi.json): Every operation an API key may call, with scopes, schemas and errors. No authentication needed to read it.

## How to build an experience

Follow this order. Each step is one request.

1. List templates: `GET /api/v1/templates`. Pick a template and read its `slots` and `editor_required`.
2. Create: `POST /api/v1/experiences/` with `name` and `template_type`. Keep the returned `id`.
3. Upload or import assets: `POST /api/v1/assets/upload?experience_id={id}` as multipart, or `POST /api/v1/assets/import-url` with a public https URL. Keep the returned `cdn_path`.
4. Score the target image: `POST /api/v1/assets/target-quality?cdn_path={cdn_path}`. On grade `poor`, ask for a different image.
5. Set slots: `POST /api/v1/experiences/{id}/slots/{slot_id}` with `cdn_path`. For the video slot of `video_on_surface`, always send `video_aspect_ratio` (width divided by height). The server fits the video plane to the target image, and `fit` is `contain` (default), `cover` or `stretch`. Setting the target image later re-fits the plane. For models use `POST /api/v1/experiences/{id}/objects`.
6. Validate: `POST /api/v1/experiences/{id}/validate`. Fix every item in `problems` until `ok` is true.
7. Publish: `POST /api/v1/experiences/{id}/publish`. The response carries `hosted_url`.
8. Read results: `GET /api/v1/analytics/summary?experience_id={id}` and `GET /api/v1/leads?experience_id={id}`.

## Templates that need no editor

- `video_on_surface`: a target image and a video. The video plays on top of the scanned image.
- `product_float`: a target image and one 3D model that floats above it.
- `vr_360_video`: one 360 degree video. Needs the Studio plan and the 360 video add-on.

Every other template needs the visual editor to place content. Check `editor_required` in `GET /api/v1/templates`.

## Rules

- Send `Authorization: Bearer mnrv_live_...` on every request. Never put a key in a URL.
- Scopes: `experiences`, `publish`, `assets`, `analytics`, `leads`. A missing scope answers 403 `scope_missing`. A route outside the OpenAPI document answers 403 `endpoint_forbidden`.
- Rate limit: 120 requests per minute per key. Past it you get 429 `rate_limited` with a `Retry-After` header in seconds. Wait that long.
- Errors are JSON with `detail`, `code` and sometimes `field` and `upgrade_url`. Branch on `code`. Request validation errors use `code` `invalid_request`.
- Quota and plan errors answer 402 with a `code` such as `publish_limit`, `create_limit`, `plan_required` or `addon_required`, and an `upgrade_url`. Stop, and tell the account owner to open that URL. Do not retry.
- Send an `Idempotency-Key` header on create, publish, add object and import by URL. A repeat with the same key within 24 hours replays the first response.
- Import by URL takes public https URLs only, default port, no credentials, and is limited to 30 per 10 minutes.
- Use the slot and object routes to fill an experience. Avoid sending a whole config through `PATCH /api/v1/experiences/{id}` unless you must.

## Optional

- [Pricing](https://mnrvar.com/pricing): Plans and what each includes.
- [Privacy policy](https://mnrvar.com/privacy)
- [Terms of service](https://mnrvar.com/terms)