REST API Reference

This page is generated from the OpenAPI 3.1 document at /api/v1/openapi.json, so it lists exactly what the server implements: 49 operations. Point any OpenAPI tool at that URL for client generation or a Postman collection.

Base URL#

base

https://lumorig.com/api/v1

Self-hosted servers use their own origin (MF_PUBLIC_URL). Every request needs Authorization: Bearer lr_sk_… except the ones marked no key needed. See Authentication.

Convention	Detail
Bodies	JSON (Content-Type: application/json). Uploads also take multipart/form-data.
Lists	`{ "object": "list", "data": [ … ] }`
Deletes	`{ "id": "…", "object": "…", "deleted": true }`
Long work	202 with a Job. Poll `GET /jobs/{id}?wait=60`, stream `/jobs/{id}/events`, or use a webhook.
Errors	`{ "error": { "code", "message", "details" } }`, see Errors.
Ids	Prefixed: `msc_` mascot, `anm_` animation, `cnv_` canvas, `ver_` version, `job_`, `file_`, `whk_`, `key_`.

Mascots#

GET/mascotsList mascots
POST/mascotsCreate a mascot
GET/mascots/{id}Get a mascot
PATCH/mascots/{id}Update a mascot
DELETE/mascots/{id}Delete a mascot
GET/mascots/{id}/specGet the MascotSpec
PUT/mascots/{id}/specReplace the MascotSpec (new version)
POST/mascots/{id}/recolorRecolor (instant)
POST/mascots/{id}/editEdit by instruction
POST/mascots/{id}/variantsCreate a rig-compatible look variant
GET/mascots/{id}/versionsList versions
POST/mascots/{id}/versions/{versionId}/restoreRestore a version
GET/mascots/{id}/previewRender a still
GET/mascots/{id}/bundlePlayer bundle for <lumorig-player>
POST/mascots/{id}/shareCreate an expiring share link
POST/analyzeMascot concepts from a website

List mascots#

GET/mascots

Response · 200

Mascots

List mascots response
Field	Type	Notes
`object`	"list"
`data`	Mascot[]

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create a mascot#

POST/mascots

prompt designs a new mascot; upload_id/image_url rebuilds an existing one as a rigged vector; spec imports a MascotSpec directly (synchronous, 201).

Request body

One of 2 shapes:

Option 1 · prompt, style…

Create a mascot body, option 1
Field	Type	Notes
`prompt`	string	3–2000 chars
`style`	string	0–400 chars
`upload_id`	string
`image_url`	string (uri)
`name`	string	0–80 chars
`notes`	string	0–1000 chars
`detail`	"standard" \| "high"	high: richer rendering at a higher credit price
`max_cost_usd`	number	> 0

Option 2 · with spec

Create a mascot body, option 2
Field	Type	Notes
`spec`required	MascotSpec
`name`	string

Response · 202

Mascot and its generation job

Create a mascot response
Field	Type	Notes
`mascot`	Mascot
`job`	Job

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"a sleepy moth who guards the docs","style":"outlined"}'

Get a mascot#

GET/mascots/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`include`	"spec" · query

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123?include=spec" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Update a mascot#

PATCH/mascots/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Update a mascot body
Field	Type	Notes
`name`	string
`public`	boolean

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X PATCH "https://lumorig.com/api/v1/mascots/msc_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"public":true}'

Delete a mascot#

DELETE/mascots/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Deleted

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/mascots/msc_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Get the MascotSpec#

GET/mascots/{id}/spec

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`version`	string · query

Response · 200

Spec

A MascotSpec object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/spec" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Replace the MascotSpec (new version)#

PUT/mascots/{id}/spec

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

A MascotSpec object.

Response · 200

Mascot

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X PUT "https://lumorig.com/api/v1/mascots/msc_123/spec" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d @spec.json

Recolor (instant)#

POST/mascots/{id}/recolor

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Recolor (instant) body
Field	Type	Notes
`palette`required	record<string, string>

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/recolor" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"palette":{"body":"#3a5bff"}}'

Edit by instruction#

POST/mascots/{id}/edit

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Edit by instruction body
Field	Type	Notes
`instruction`required	string
`max_cost_usd`	number

Response · 202

Job

A Job object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/edit" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"make the antennae longer"}'

Create a rig-compatible look variant#

POST/mascots/{id}/variants

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create a rig-compatible look variant body
Field	Type	Notes
`name`required	string
`instruction`required	string

Response · 202

Job

A Job object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/variants" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"winter","instruction":"wearing a knitted scarf"}'

List versions#

GET/mascots/{id}/versions

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Versions

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/versions" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Restore a version#

POST/mascots/{id}/versions/{versionId}/restore

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`versionId`required	string · path

Response · 200

Mascot

A Mascot object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/versions/ver_123/restore" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Render a still#

GET/mascots/{id}/preview

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`format`	string · query
`animation`	string · query
`t`	number · query
`size`	number · query
`v`	string · query

Response · 200 · image/png, image/svg+xml

Image

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/preview?format=png&animation=wave&t=0.4&size=512" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Player bundle for <lumorig-player>#

GET/mascots/{id}/bundleno key needed

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`token`	string · query	Signed share token for private mascots

Response · 200

Bundle

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/bundle"

POST/mascots/{id}/share

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create an expiring share link body
Field	Type	Notes
`ttl_seconds`	integer

Response · 200

Share link

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/share" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds":86400}'

Mascot concepts from a website#

POST/analyze

Request body

Mascot concepts from a website body
Field	Type	Notes
`url`required	string (uri)

Response · 202

Job (result: brand analysis + 3 concepts)

A Job object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/analyze" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Animations#

GET/mascots/{id}/animationsList animations
POST/mascots/{id}/animationsCreate an animation
GET/mascots/{id}/animations/{animationId}Get an animation (with clip)
DELETE/mascots/{id}/animations/{animationId}Delete an animation
POST/mascots/{id}/animations/batchCreate several described animations
POST/mascots/{id}/suggestionsSuggest signature animations

List animations#

GET/mascots/{id}/animations

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Animations

List animations response
Field	Type	Notes
`object`	"list"
`data`	Animation[]

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/animations" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create an animation#

POST/mascots/{id}/animations

preset is instant and free (201). prompt runs the motion designer (202 + job). reference_upload_id (an uploaded MP4/MOV/WebM) makes the mascot perform the motion in the video (202 + job). clip saves a hand-authored AnimationClip.

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

One of 4 shapes:

Option 1 · with preset

Create an animation body, option 1
Field	Type	Notes
`preset`required	enum (15 values)	idle, wave, nod, shake, bounce, celebrate, jump, talk, sad, surprised, dance, think, working, listen, sleep
`intensity`	number	0.25–2
`duration`	number	0.3–20
`name`	string	0–60 chars

Option 2 · with prompt

Create an animation body, option 2
Field	Type	Notes
`prompt`required	string	3–1000 chars
`duration`	number	0.3–20
`name`	string	0–60 chars
`max_cost_usd`	number	> 0

Option 3 · with clip, name

Create an animation body, option 3
Field	Type	Notes
`clip`required	any
`name`required	string	0–60 chars

Option 4 · with reference_upload_id

Create an animation body, option 4
Field	Type	Notes
`reference_upload_id`required	string	An uploaded MP4/MOV/WebM whose motion the mascot should perform
`prompt`	string	0–1000 chars
`duration`	number	0.3–12
`name`	string	0–60 chars
`max_cost_usd`	number	> 0

Response · 201

Animation (preset/clip) or {job} (prompt)

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/animations" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"preset":"wave","intensity":1.2}'

Get an animation (with clip)#

GET/mascots/{id}/animations/{animationId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`animationId`required	string · path

Response · 200

Animation

A Animation object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/animations/anm_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Delete an animation#

DELETE/mascots/{id}/animations/{animationId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`animationId`required	string · path

Response · 200

Deleted

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/mascots/msc_123/animations/anm_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create several described animations#

POST/mascots/{id}/animations/batch

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create several described animations body
Field	Type	Notes
`prompts`required	string[]	max 8 items
`duration`	number

Response · 202

Jobs

Create several described animations response
Field	Type	Notes
`object`	"list"
`data`	Job[]

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/animations/batch" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompts":["hops twice, then bows","peeks out from behind the desk"]}'

Suggest signature animations#

POST/mascots/{id}/suggestions

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Suggest signature animations body
Field	Type	Notes
`use_case`	string

Response · 200

Finished job (result.suggestions)

A Job object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/suggestions" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"use_case":"docs site helper that appears on empty search results"}'

Exports#

POST/mascots/{id}/scenesCreate an illustrated vector scene
POST/mascots/{id}/exportsExport
GET/files/{id}Download a file

Create an illustrated vector scene#

POST/mascots/{id}/scenes

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create an illustrated vector scene body
Field	Type	Notes
`prompt`required	string
`size`	"square" \| "wide" \| "banner" \| "portrait"
`animation`	string
`t`	number
`max_cost_usd`	number

Response · 202

Job (result.svg, result.png)

A Job object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/scenes" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"cozy desk at night, leave the left half calm for copy","size":"wide"}'

Export#

POST/mascots/{id}/exports

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Export body
Field	Type	Notes
`format`required	enum (13 values)	gif, mp4, webm, webp, apng, sprite, lottie, animated-svg, png, svg, sticker, logo, logo-png
`animation`	string
`size`	integer	64–2048
`fps`	integer	6–60
`background`	string	pattern ^#[0-9a-fA-F]{6}$
`t`	number	≥ 0
`version_id`	string

Response · 202

Job (result.file)

A Job object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/exports" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"format":"lottie","animation":"wave"}'

Download a file#

GET/files/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path
`download`	string · query

Response · 200

File bytes

curl

curl "https://lumorig.com/api/v1/files/file_123?download=1" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -o mascot.json

Canvases#

GET/mascots/{id}/canvasesList canvases
POST/mascots/{id}/canvasesCreate a canvas
PATCH/mascots/{id}/canvases/{canvasId}Update a canvas
DELETE/mascots/{id}/canvases/{canvasId}Delete a canvas

List canvases#

GET/mascots/{id}/canvases

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Response · 200

Canvases

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/mascots/msc_123/canvases" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create a canvas#

POST/mascots/{id}/canvases

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)

Request body

Create a canvas body
Field	Type	Notes
`name`required	string
`template`	"chatbot" \| "ai_agent" \| "onboarding"
`graph`	CanvasGraph

Response · 201

Canvas

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/mascots/msc_123/canvases" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"assistant","template":"chatbot"}'

Update a canvas#

PATCH/mascots/{id}/canvases/{canvasId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`canvasId`required	string · path

Request body

Update a canvas body
Field	Type	Notes
`name`	string
`graph`	CanvasGraph

Response · 200

Canvas

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X PATCH "https://lumorig.com/api/v1/mascots/msc_123/canvases/cnv_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"helper"}'

Delete a canvas#

DELETE/mascots/{id}/canvases/{canvasId}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path	Mascot id (msc_…)
`canvasId`required	string · path

Response · 200

Deleted

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/mascots/msc_123/canvases/cnv_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Jobs#

GET/jobsList jobs
GET/jobs/{id}Get a job (long-poll with ?wait=seconds, max 120)
GET/jobs/{id}/eventsStream job events (SSE)
POST/jobs/{id}/cancelCancel a job

List jobs#

GET/jobs

Parameters

Parameters
Field	Type	Notes
`status`	string · query
`type`	string · query
`mascot_id`	string · query
`limit`	string · query

Response · 200

Jobs

List jobs response
Field	Type	Notes
`object`	"list"
`data`	Job[]

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/jobs" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Get a job (long-poll with ?wait=seconds, max 120)#

GET/jobs/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path
`wait`	integer · query	≤ 120

Response · 200

Job

A Job object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/jobs/job_123?wait=60" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Stream job events (SSE)#

GET/jobs/{id}/events

Parameters

Parameters
Field	Type	Notes
`id`required	string · path
`after`	integer · query

Response · 200 · text/event-stream

text/event-stream: queued, started, progress, tool_call, tool_input_delta, draft, usage, finished

curl

curl -N "https://lumorig.com/api/v1/jobs/job_123/events" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Cancel a job#

POST/jobs/{id}/cancel

Parameters

Parameters
Field	Type	Notes
`id`required	string · path

Response · 200

Job

A Job object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/jobs/job_123/cancel" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Uploads#

POST/uploadsUpload an image

Upload an image#

POST/uploads

Request body · multipart/form-data or application/json

multipart/form-data

Upload an image body
Field	Type	Notes
`file`	string (binary)

application/json

Upload an image body
Field	Type	Notes
`url`	string (uri)

Response · 201

Uploaded file

A File object.

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/uploads" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -F "file=@./mascot.png"

List webhooks#

GET/webhooks

Response · 200

Webhooks

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/webhooks" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create a webhook#

POST/webhooks

Deliveries are signed: Lumorig-Signature: t=<unix>,v1=<hex HMAC-SHA256 of "t.body">.

Request body

Create a webhook body
Field	Type	Notes
`url`required	string (uri)
`events`	"job.succeeded" \| "job.failed" \| "job.canceled" \| "*"[]	items: job.succeeded, job.failed, job.canceled, *

Response · 201

Webhook (secret shown once)

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/webhooks" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://your.app/hooks/lumorig","events":["job.succeeded","job.failed"]}'

Delete a webhook#

DELETE/webhooks/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path

Response · 200

Deleted

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/webhooks/whk_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Workspace#

GET/workspaceGet the current workspace
GET/workspace/membersList members
GET/workspace/invitesList pending invites
POST/workspace/invitesInvite someone by email

Get the current workspace#

GET/workspace

Name, plan, your role and seats (limit, members, pending, used, available). With an API key: the key's workspace. With a studio session: the active workspace (the Lumorig-Workspace header selects another one you belong to).

Response · 200

Workspace

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/workspace" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

List members#

GET/workspace/members

Response · 200

Members (owner first)

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/workspace/members" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

List pending invites#

GET/workspace/invites

Admins and the owner. Studio session only.

Response · 200

Invites

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/workspace/invites" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Invite someone by email#

POST/workspace/invites

Studio session only (API keys get 403 session_required). A pending invite holds a seat for 7 days; beyond the plan's seats the response is 402 seat_limit with details: { seats, used, members, pending }.

Request body

Invite someone by email body
Field	Type	Notes
`email`required	string (email)
`role`	"member" \| "admin"

Response · 201

Invite and its link (shown once)

Invite someone by email response
Field	Type	Notes
`invite`	object
`invite_url`	string

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/workspace/invites" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"…"}'

Account#

DELETE/keys/{id}Revoke an API key
GET/keysList API keys
POST/keysCreate an API key
GET/usageUsage and spend
GET/creditsCredit balance, plan, and per-action prices

Revoke an API key#

DELETE/keys/{id}

Parameters

Parameters
Field	Type	Notes
`id`required	string · path

Response · 200

Revoked

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X DELETE "https://lumorig.com/api/v1/keys/key_123" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

List API keys#

GET/keys

Response · 200

Keys

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/keys" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Create an API key#

POST/keys

Request body

Create an API key body
Field	Type	Notes
`name`	string

Response · 201

Key (shown once)

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl -X POST "https://lumorig.com/api/v1/keys" \
  -H "Authorization: Bearer $LUMORIG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"CI"}'

Usage and spend#

GET/usage

Response · 200

Usage

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/usage" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Credit balance, plan, and per-action prices#

GET/credits

Model-backed jobs hold credits up front and refund them on failure. Without enough credits they return 402 insufficient_credits.

Response · 200

Credits

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/credits" \
  -H "Authorization: Bearer $LUMORIG_API_KEY"

Catalog#

GET/presetsList animation presets
GET/stylesList style presets
GET/canvas-templatesList canvas templates

List animation presets#

GET/presetsno key needed

Response · 200

Presets

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/presets"

List style presets#

GET/stylesno key needed

Response · 200

Styles

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/styles"

List canvas templates#

GET/canvas-templatesno key needed

Response · 200

Templates

object

Errors: 400 · 401 · 404 → ErrorResponse

curl

curl "https://lumorig.com/api/v1/canvas-templates"

Schemas#

Shared objects referenced above. The full MascotSpec and AnimationClip formats are explained in MascotSpec & AnimationClip.

MascotSpec#

MascotSpec fields
Field	Type	Notes
`specVersion`required	1
`name`required	string	1–∞ chars
`description`required	string
`archetype`required	"biped" \| "quadruped" \| "blob" \| "winged" \| "object" \| "custom"
`canvas`required	object
`palette`required	object[]
`parts`required	object[]
`anchors`required	object[]

AnimationClip#

AnimationClip fields
Field	Type	Notes
`clipVersion`required	1
`name`required	string	1–∞ chars
`duration`required	number	Seconds0.2–20
`loop`required	boolean
`tracks`required	object \| object[]
`modifiers`required	object \| object \| object[]

CanvasGraph#

CanvasGraph fields
Field	Type	Notes
`canvasVersion`required	1
`inputs`required	object[]
`states`required	object[]
`initial`required	string	pattern ^[a-z][a-z0-9_]*$
`transitions`required	object[]

ErrorResponse#

ErrorResponse fields
Field	Type	Notes
`error`	object

File#

File fields
Field	Type	Notes
`id`	string
`object`	"file"
`kind`	string
`mime`	string
`bytes`	integer
`url`	string
`created_at`	string

Job#

Job fields
Field	Type	Notes
`id`	string
`object`	"job"
`type`	enum (9 values)	generate, reconstruct, edit, variant, animate, export, analyze, suggest, scene
`status`	"queued" \| "running" \| "succeeded" \| "failed" \| "canceled"
`mascot_id`	string \| null
`result`	any
`error`	string \| null
`cost_usd`	number
`created_at`	string
`started_at`	string \| null
`finished_at`	string \| null

Animation#

Animation fields
Field	Type	Notes
`id`	string
`name`	string
`source`	"preset" \| "prompt" \| "custom"
`preset`	enum (15 values)	idle, wave, nod, shake, bounce, celebrate, jump, talk, sad, surprised, dance, think, working, listen, sleep
`duration`	number
`loop`	boolean
`clip`	AnimationClip

Mascot#

Mascot fields
Field	Type	Notes
`id`	string
`object`	"mascot"
`name`	string
`status`	"generating" \| "ready" \| "failed"
`source`	"prompt" \| "image" \| "svg"
`fidelity`	number \| null	Rebuild similarity to the upload (0–1)
`needs_review`	boolean
`palette`	object[]
`parts`	object[]
`animations`	Animation[]
`preview_url`	string \| null
`bundle_url`	string

ExportFormat#

REST API

Base URL#

Mascots#

List mascots#

Create a mascot#

Get a mascot#

Update a mascot#

Delete a mascot#

Get the MascotSpec#

Replace the MascotSpec (new version)#

Recolor (instant)#

Edit by instruction#

Create a rig-compatible look variant#

List versions#

Restore a version#

Render a still#

Player bundle for <lumorig-player>#

Create an expiring share link#

Mascot concepts from a website#

Animations#

List animations#

Create an animation#

Get an animation (with clip)#

Delete an animation#

Create several described animations#

Suggest signature animations#

Exports#

Create an illustrated vector scene#

Export#

Download a file#

Canvases#

List canvases#

Create a canvas#

Update a canvas#

Delete a canvas#

Jobs#

List jobs#

Get a job (long-poll with ?wait=seconds, max 120)#

Stream job events (SSE)#

Cancel a job#

Uploads#

Upload an image#

Webhooks#

List webhooks#

Create a webhook#

Delete a webhook#

Workspace#

Get the current workspace#

List members#

List pending invites#

Invite someone by email#

Account#

Revoke an API key#

List API keys#

Create an API key#

Usage and spend#

Credit balance, plan, and per-action prices#

Catalog#

List animation presets#

List style presets#

List canvas templates#

Schemas#

MascotSpec#

AnimationClip#

CanvasGraph#

ErrorResponse#

File#

Job#

Animation#

Mascot#

ExportFormat#