Delivery API — IngevoraMirage

Delivery APIThe delivery API tells your server which published version of a face lens or screen effect to download, and where its files are. It has four read-only routes, all at https://mirage-api.ingevora.com.AuthenticationSend your API key in the X-Api-Key header of every request. The delivery API accepts nothing else. See API keys.Routes

Route

Answers with

GET /v1/lenses/:lensId

The latest published version of a face lens

GET /v1/lenses/:lensId/versions/:version

One pinned version of a face lens

GET /v1/effects/:effectId

The latest published version of a screen effect

GET /v1/effects/:effectId/versions/:version

One pinned version of a screen effect

Ids are UUIDs; copy them from the Developers page in the editor. A version is a whole number from 1. One key works for both products.

bash

# The latest version of a face lens
curl -H "X-Api-Key: mk_…" https://mirage-api.ingevora.com/v1/lenses/8f3c2a10-…

# Version 2 of a screen effect
curl -H "X-Api-Key: mk_…" https://mirage-api.ingevora.com/v1/effects/5d1e7b42-…/versions/2

Face lens answer

json

{
  "data": {
    "lensId": "8f3c2a10-…",
    "version": 3,
    "manifestUrl": "https://…/lenses/8f3c2a10-…/3/manifest.json",
    "manifestSha256": "9f2c…",
    "totalBytes": 184522,
    "minEngineVersion": 1,
    "publishedAt": "2026-10-02T09:30:00.000Z",
    "previewUrl": "https://…/lenses/8f3c2a10-…/3/preview.png"
  },
  "success": true
}

Field

Type

Meaning

lensId

string

The face lens's id.

version

integer

The version number, from 1.

manifestUrl

string

Where to download this version's manifest.json. Its images sit in the same folder.

manifestSha256

string

The SHA-256 of the manifest's exact bytes, as 64 lowercase hex characters.

totalBytes

integer

The manifest's size plus the sizes of all the images it uses.

minEngineVersion

integer

The lowest renderer engine version that can draw this version.

publishedAt

string

When it was published, as an ISO 8601 time in UTC.

previewUrl

string or null

A preview PNG of at most 512 × 512 pixels, or null when there is none. The field is always present. The preview is not part of the package and the hashes don't cover it, so never rely on it.

Screen effect answer

json

{
  "data": {
    "effectId": "5d1e7b42-…",
    "version": 2,
    "manifestUrl": "https://…/effects/5d1e7b42-…/2/manifest.json",
    "manifestSha256": "41ad…",
    "totalBytes": 96310,
    "minEngineVersion": 1,
    "durationMs": 2000,
    "publishedAt": "2026-10-01T16:05:12.000Z"
  },
  "success": true
}

The fields mean the same as for a face lens, with effectId in place of lensId. durationMs is the effect's length in milliseconds. A screen effect has no previewUrl.What answers 404All of these give the same 404, "Lens not found" or "Screen effect not found":

an id that doesn't exist;

an item that belongs to another workspace;

an item that has never been published;

on a pinned route, a version number that doesn't exist.

The answers are the same on purpose, so nobody can use the API to learn what other workspaces have. A mistyped path also answers 404. Archived items keep answering normally.Other errors

401 "Missing or invalid API key" — the header is missing, or the key is unknown or revoked.

403 "Face lenses are not enabled for this tenant" or "Screen effects are not enabled for this tenant" — that product is off for your workspace ("tenant" is the API's word for a workspace). The Developers page shows which products are on.

400 — the id is not a UUID, or the version is not a whole number from 1 to 2147483647.

Every error comes in the same envelope. See Errors and limits.CountingEvery delivery call made with a valid key counts against that key, per UTC day, whatever the answer: a 404 counts too. Downloading the manifest and the images is not a delivery call and is not counted. Cache answers on your server instead of asking on every app launch.Answers can growNew fields can appear in these answers without a new API version (previewUrl was one). Read answers leniently and ignore fields you don't know. Removing or changing a field would be announced first. See Downloading safely.The interactive API reference is at https://mirage-api.ingevora.com/docs.