verse --api --docs

Build on the Verse platform

One API key unlocks the whole stack: AI chat and research, text-to-speech, translation, vision, Versona characters with 3D models, workflow automation, and a relay that lets your code drive the Verse desktop app. Every call is encrypted with your secret and metered in tokens.

16+ endpoints encrypted payloads token metered webhooks
01

Quick Start

1

Get your keys

Sign in, open your account's Developer Settings, and generate an API key + secret pair. The secret is shown once — store it safely.

2

Encrypt the payload

Build the service's JSON body, encrypt it with your API secret, and wrap it in the request envelope with your key.

3

Call the endpoint

POST to any /api/Verse/* service. The response returns your result plus the tokens remaining on your account.

02

Authentication

Verse API endpoints authenticate with an API key and an encrypted payload instead of a bearer header: the body of every service call is a JSON object encrypted with your API secret. The server looks up your key, decrypts with the paired secret, runs the service, and deducts the service's token cost from your balance.

  1. Generate credentials in Developer Settings — one active key + secret pair per app.
  2. Serialize the service parameters to JSON (each endpoint's payload is documented below).
  3. Encrypt that JSON string with your API secret and place it in payload.
  4. Send the envelope — the server validates the key, decrypts, and executes.
  5. Read RemainingTokens from the response to track your spend.
Request envelope — every /api/Verse call 
{
  "payload": "<service JSON, encrypted with your API secret>",
  "ApiKey":  "<your API key>"
}
Your API secret never travels in a request — it only encrypts payloads client-side. Never embed it in shipped front-end code; call the Verse API from your backend.
03

AI Services

Core intelligence endpoints. All are POST, all use the encrypted envelope, all deduct tokens per call. Click an endpoint to expand it.

04

Versona API

Versonas are AI characters with a personality, a voice, a knowledge base, and a 3D GLB avatar. These endpoints let your app list a user's Versonas, chat with them (optionally with audio), and download their models for rendering.

05

Workflows API

Workflows are visual automations built in the Verse workflow editor (~150 node types, ~100 integrations). From the API you can enumerate them, inspect one, and trigger a run programmatically.

06

Webhook Triggers

Any workflow with a Webhook trigger node gets its own secret URL. Hitting it starts the workflow with your request's method, path, headers, query, and body as trigger input — the standard way to connect outside systems to Verse automations.

If the workflow contains a Respond to Webhook node it runs synchronously (about a 30 s budget) and the call returns that captured response. Otherwise the run is fire-and-forget and you get an immediate acknowledgment.
07

Versona Desktop Relay

The relay pairs the Verse desktop app with the server so workflows and scripts can drive a machine: run an agent, call a tool, execute code, chat with a local Versona. Your program enqueues commands; the desktop app long-polls, executes, and posts results. Desktop-side calls authenticate with X-Api-Key + X-Api-Secret headers; enqueue/result calls use your signed-in session (Bearer JWT).

08

Responses & Errors

Success 
{
  "RemainingTokens": 95,
  "ServiceResponse": { /* service-specific result */ }
}
Error 
{
  "error": "Error description",
  "code": 400
}
StatusMeaning
200Success — result in ServiceResponse, balance in RemainingTokens.
400Malformed envelope or payload that fails decryption / validation.
401Unknown or inactive API key.
402 / 403Insufficient token balance for the requested service.
429Rate limited — back off and retry.
500Service error — safe to retry idempotent calls.
09

Desktop App Kit

Build apps that run inside the Verse desktop. An app is a tiny package — a manifest, one script, and an icon — created with the Verse Desktop App Dev VS Code extension, which scaffolds projects, previews them in desktop and mobile frames, validates the manifest, and packages a ZIP ready for the App Store.

manifest.json

Name, semver version, description, entry script, icon, category, optional size and price.

index.js

Plain JavaScript, one file. Declares initApp(appWindow) — your app's entry point. No modules, no Node APIs.

icon.png

128×128 icon. Optional extras: style.css, README.md.

Minimal app 
// index.js — the whole app
function initApp(appWindow) {
    appWindow.setTitle('Hello Verse');
    appWindow.setContent('<h2>Hello from my first Verse app</h2>');

    // appWindow API: setContent(html), getContentElement(),
    // setTitle(), close() — plus resize()/maximize()/minimize()
    // when running on desktop.
}
The extension ships commands for create project, desktop / mobile preview (375×700 frame), validate manifest, and package to ZIP — plus snippets like vinit, vcard, vbutton, and vfetch.
10

App Store

Packaged apps upload to the Verse App Store and become installable on every user's desktop. Store endpoints use your signed-in session (Bearer JWT).