Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
// The v1 agents API contract: one router, one envelope, one error shape.
//
// Every route under /api/v1/{agents,runs,automations,models,me,intel,strategies}
// is declared in api/v1/rest.js as a row of `defineRouter`. This module gives
// each row the same behavior:
//
// • Auth three.ws API key (`Authorization: Bearer sk_live_…`), OAuth
// access token, or a signed-in browser session.
// • Scopes declared per route, enforced for key and OAuth callers.
// • CSRF cookie-authenticated writes must carry X-CSRF-Token.
// • Limits per principal (key › user › ip) via limits.apiV1.
// • Metering every call lands in usage_events as kind 'api'.
// • Envelope success → { data, meta: { requestId, timestamp, … } }
// failure → { error: { code, message, details }, meta }
// • Replay an authenticated write carrying `Idempotency-Key` runs once;
// a retry with the same key and body gets the stored response
// back (header `Idempotent-Replayed: true`) for 24 hours.
//
// A handler returns its payload, or `created(payload)` for a 201, or writes
// the response itself (the SSE stream) and returns nothing. To fail, throw
// `apiError(status, code, message, details)`. Anything else that throws is a
// 500 with a sanitized message; the stable error codes are listed in
// docs/api-reference.md.
import { randomUUID } from 'node:crypto';
import { cors, readJson, setRateLimitHeaders } from '../http.js';
import { authenticateBearer, extractBearer, getSessionUser, hasScope } from '../auth.js';
import { checkCsrf } from '../csrf.js';
import { limits, clientIp } from '../rate-limit.js';
import { recordEvent } from '../usage.js';
import { acquireLock, releaseLock } from '../cache.js';
import {
IDEMPOTENCY_KEY_MAX,
idempotencyStoreKey,
normalizeIdempotencyKey,
readIdempotent,
sha256Hex,
writeIdempotent,
} from '../idempotency.js';
export class ApiError extends Error {
/**
* @param {number} status
* @param {string} code
* @param {string} message
* @param {object|null} [details]
*/
constructor(status, code, message, details = null) {
super(message);
this.status = status;
this.code = code;
this.details = details;
}
}
/** Build an ApiError to throw. */
export function apiError(status, code, message, details = null) {
return new ApiError(status, code, message, details);
}
const CREATED = Symbol('created');
/** Mark a handler result as a 201 Created. */
export function created(data) {
return { [CREATED]: true, data };
}
/** Attach pagination to a list result: `{ items, hasMore, nextCursor }`. */
export function page(items, { hasMore, nextCursor = null }) {
return { __page: true, items, hasMore: Boolean(hasMore), nextCursor };
}
function meta(ctx, extra = {}) {
return { requestId: ctx.requestId, timestamp: new Date().toISOString(), ...extra };
}
function send(res, status, body) {
if (res.headersSent || res.writableEnded) return;
res.statusCode = status;
res.setHeader('content-type', 'application/json; charset=utf-8');
res.setHeader('cache-control', 'no-store');
res.end(JSON.stringify(body));
}
/** Write an error envelope. */
export function sendError(res, ctx, status, code, message, details = null) {
send(res, status, { error: { code, message, details }, meta: meta(ctx) });
}
/** Compile '/agents/:id/runs' into a matcher returning params or null. */
export function compilePath(pattern) {
const parts = pattern.split('/').filter(Boolean);
return (segments) => {
if (segments.length !== parts.length) return null;
const params = {};
for (let i = 0; i < parts.length; i++) {
const p = parts[i];
if (p.startsWith(':')) params[p.slice(1)] = segments[i];
else if (p !== segments[i]) return null;
}
return params;
};
}
async function resolvePrincipal(req) {
const session = await getSessionUser(req);
if (session) return { userId: session.id, source: 'session', scope: 'all' };
const bearer = await authenticateBearer(extractBearer(req));
if (!bearer) return null;
return {
userId: bearer.userId,
source: bearer.source,
scope: bearer.scope || '',
apiKeyId: bearer.apiKeyId,
clientId: bearer.clientId,
};
}
/**
* Build the single request handler for a table of routes.
*
* @param {object} o
* @param {string} o.base URL prefix stripped before matching, e.g. '/api/v1'
* @param {Array<{ method: string, path: string, name: string, auth: 'public'|'optional'|'required',
* scope?: string, csrf?: boolean, handler: (ctx: object) => any }>} o.routes
*/
export function defineRouter({ base, routes }) {
const compiled = routes.map((r) => ({ ...r, match: compilePath(r.path) }));
const allMethods = [...new Set(routes.map((r) => r.method))];
return async function handler(req, res) {
const ctx = { requestId: randomUUID(), req, res };
res.setHeader('x-request-id', ctx.requestId);
if (cors(req, res, { methods: [...allMethods, 'OPTIONS'].join(','), origins: '*' })) return;
const url = new URL(req.url, 'http://internal');
let rel = url.pathname;
if (rel.startsWith(base)) rel = rel.slice(base.length);
let segments;
try {
segments = rel.split('/').filter(Boolean).map(decodeURIComponent);
} catch {
return sendError(res, ctx, 400, 'bad_request', 'Malformed URL encoding.');
}
let route = null;
let params = null;
let pathMatched = false;
for (const r of compiled) {
const p = r.match(segments);
if (!p) continue;
pathMatched = true;
if (r.method === req.method) {
route = r;
params = p;
break;
}
}
if (!route) {
return pathMatched
? sendError(res, ctx, 405, 'method_not_allowed', `${req.method} is not supported on ${url.pathname}.`)
: sendError(res, ctx, 404, 'not_found', `No route matches ${req.method} ${url.pathname}.`);
}
const started = Date.now();
let principal = null;
try {
if (route.auth !== 'public') {
principal = await resolvePrincipal(req);
if (route.auth === 'required' && !principal) {
throw apiError(
401,
'unauthorized',
'Authenticate with a three.ws API key (`Authorization: Bearer sk_live_…`) or sign in. Create a key at /dashboard/developers.',
);
}
if (principal && principal.source !== 'session' && route.scope && !hasScope(principal.scope, route.scope)) {
throw apiError(403, 'insufficient_scope', `This route requires the "${route.scope}" scope.`, {
required: route.scope,
});
}
}
const rlKey = principal?.apiKeyId
? `key:${principal.apiKeyId}`
: principal?.userId
? `user:${principal.userId}`
: `ip:${clientIp(req)}`;
const rl = await limits.apiV1(rlKey);
const retryAfter = Math.max(1, setRateLimitHeaders(res, rl) || 1);
if (!rl.success) {
res.setHeader('retry-after', String(retryAfter));
throw apiError(429, 'rate_limited', 'Too many requests. Slow down and retry.', { retryAfterSeconds: retryAfter });
}
const writes = ['POST', 'PUT', 'PATCH', 'DELETE'].includes(req.method);
let body = {};
if (writes && req.method !== 'DELETE' && hasBody(req)) {
try {
body = (await readJson(req)) || {};
} catch (err) {
throw apiError(400, 'bad_json', err?.message || 'The request body must be JSON.');
}
if (!body || typeof body !== 'object' || Array.isArray(body)) {
throw apiError(400, 'bad_json', 'The request body must be a JSON object.');
}
}
if (writes && principal?.source === 'session' && route.csrf !== false) {
const verdict = await checkCsrf({ headers: req.headers, body }, principal.userId);
if (!verdict.ok) throw apiError(403, verdict.code, verdict.message);
}
const idem = writes && principal ? idempotencyKey(req, principal, route, body) : null;
if (idem) {
const stored = await readIdempotent(idem.key);
if (stored) {
if (stored.bodyHash !== idem.bodyHash) {
throw apiError(422, 'idempotency_key_reused', 'This Idempotency-Key was already used with a different request body.');
}
res.setHeader('idempotent-replayed', 'true');
meter(route, principal, 'ok', started);
return send(res, stored.status, stored.body);
}
if (!(await acquireLock(`${idem.key}:lock`, 120))) {
throw apiError(409, 'idempotency_in_progress', 'A request with this Idempotency-Key is still running. Retry shortly.');
}
ctx.idem = idem;
}
const query = Object.fromEntries(url.searchParams);
let result;
try {
result = await route.handler({ ...ctx, principal, params, query, body, ip: clientIp(req) });
} finally {
if (ctx.idem) releaseLock(`${ctx.idem.key}:lock`);
}
meter(route, principal, 'ok', started);
if (res.headersSent || res.writableEnded) return;
const out = shape(ctx, result);
if (ctx.idem) {
await writeIdempotent(ctx.idem.key, { ...out, bodyHash: ctx.idem.bodyHash }).catch(() => {});
}
return send(res, out.status, out.body);
} catch (err) {
meter(route, principal, 'error', started);
if (res.headersSent) {
if (!res.writableEnded) res.end();
return;
}
if (err instanceof ApiError) return sendError(res, ctx, err.status, err.code, err.message, err.details);
// A 4xx thrown by a shared helper (a SpendLimitError, an insufficient-
// credits 402) keeps its code and message; everything else is redacted.
const status = Number(err?.status);
if (status >= 400 && status < 500 && err?.code) {
return sendError(res, ctx, status, String(err.code), String(err.message || err.code), err.detail || null);
}
console.error(`[v1] ${req.method} ${url.pathname} failed (${ctx.requestId}):`, err);
return sendError(res, ctx, 500, 'internal_error', 'The request failed unexpectedly. Quote the requestId if you report it.');
}
};
}
function shape(ctx, result) {
if (result && result[CREATED]) return { status: 201, body: { data: result.data, meta: meta(ctx) } };
if (result && result.__page) {
return {
status: 200,
body: { data: result.items, meta: meta(ctx, { hasMore: result.hasMore, nextCursor: result.nextCursor }) },
};
}
return { status: 200, body: { data: result ?? null, meta: meta(ctx) } };
}
// The store is shared with the MCP studio's idempotency_key (../idempotency.js).
function idempotencyKey(req, principal, route, body) {
let key;
try {
key = normalizeIdempotencyKey(req.headers['idempotency-key']);
} catch {
throw apiError(400, 'invalid_idempotency_key', `Idempotency-Key must be at most ${IDEMPOTENCY_KEY_MAX} characters.`);
}
if (!key) return null;
return {
key: idempotencyStoreKey('v1', `${principal.userId}:${route.name}`, key),
bodyHash: sha256Hex(`${req.url}\n${JSON.stringify(body)}`),
};
}
// A write with no payload (POST /agents/:id/start) is valid; only a declared
// or non-empty body is parsed.
function hasBody(req) {
if (req.body !== undefined && req.body !== null && !(typeof req.body === 'object' && Object.keys(req.body).length === 0)) return true;
if (req.headers['content-type']) return true;
const len = Number(req.headers['content-length'] || 0);
return len > 0 || Boolean(req.headers['transfer-encoding']);
}
function meter(route, principal, status, started) {
recordEvent({
kind: 'api',
tool: route.name,
userId: principal?.userId,
apiKeyId: principal?.apiKeyId,
clientId: principal?.clientId,
status,
latencyMs: Date.now() - started,
});
}
// ── input helpers shared by the service modules ──────────────────────────────
const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
/** Throw 404 unless `id` is a UUID (every v1 resource id is one). */
export function requireUuid(id, what = 'resource') {
if (typeof id !== 'string' || !UUID_RE.test(id)) throw apiError(404, 'not_found', `No ${what} with that id.`);
return id.toLowerCase();
}
/** Parse an optional bounded integer query/body value. */
export function intParam(value, { name, min, max, fallback }) {
if (value === undefined || value === null || value === '') return fallback;
const n = Number(value);
if (!Number.isInteger(n) || n < min || n > max) {
throw apiError(400, 'invalid_parameter', `${name} must be an integer from ${min} to ${max}.`, { parameter: name });
}
return n;
}
/** Parse an optional non-negative number. */
export function numParam(value, { name, min = 0, max = Number.MAX_SAFE_INTEGER, fallback = null }) {
if (value === undefined || value === null || value === '') return fallback;
const n = Number(value);
if (!Number.isFinite(n) || n < min || n > max) {
throw apiError(400, 'invalid_parameter', `${name} must be a number from ${min} to ${max}.`, { parameter: name });
}
return n;
}
/** Parse an optional trimmed string with a max length. */
export function strParam(value, { name, max, required = false }) {
if (value === undefined || value === null || value === '') {
if (required) throw apiError(400, 'missing_parameter', `${name} is required.`, { parameter: name });
return null;
}
if (typeof value !== 'string') throw apiError(400, 'invalid_parameter', `${name} must be a string.`, { parameter: name });
const s = value.trim();
if (required && !s) throw apiError(400, 'missing_parameter', `${name} is required.`, { parameter: name });
if (s.length > max) throw apiError(400, 'invalid_parameter', `${name} must be at most ${max} characters.`, { parameter: name });
return s || null;
}