← Build on your apps

App SDK reference

`@onvoi/app-sdk` — optional helpers for code running on Onvoi. Every call wraps a documented HTTP contract, so plain fetch works too.

Setup

server.js
const { onvoi } = require('@onvoi/app-sdk');

The platform sets ONVOI_ENV_ID, ONVOI_DATA_API_URL, ONVOI_PLATFORM_URL, ONVOI_OIDC_ISSUER and a workload token in the environment.

Who is signed in

server.js
const me = await onvoi.identity.verify(req); // verifies X-Onvoi-Identity

Data and files

server.js
const items = onvoi.data.collection('items');
await items.find({ sku: 'A1' }, { as: me });
await items.create({ sku: 'B2', qty: 3 }, { as: me });
const file = await onvoi.files.upload('receipt.pdf', buf, { contentType: 'application/pdf', as: me });

Every data call acts with the signed-in person’s permissions ({ as: me }).

AI without an API key

server.js
const { text } = await onvoi.ai.chat({
  system: 'You write short product blurbs.',
  messages: [{ role: 'user', content: 'A waterproof hiking boot' }],
  model: 'fast', // or 'smart'
});

Runs on Onvoi and is paid from the running workspace’s credits. If the workspace is out of credits the call returns an error (402) your app should handle.

Events and other apps

server.js
await onvoi.events.publish('inventory.stock.low', { sku: 'A1' }, { idempotencyKey: 'A1-2026-10-24' });
await onvoi.apps.call('crm', 'crm.contacts.lookup', { email: 'a@b.co' }, { as: me });