JavaScript SDK
Official TypeScript/JavaScript client for the LiyaEngine public API.
@liyaengine/sdk is the official TypeScript/JavaScript client for the API Reference. Works in Node 18+ and any modern bundler (ESM and CJS builds are both published).
Early access
This SDK currently covers Collections, Agents, Workflows, and Evaluations. See its README for what's next.
Install
npm install @liyaengine/sdkQuickstart
import { LiyaEngine } from '@liyaengine/sdk';
const client = new LiyaEngine({ apiKey: process.env.LIYA_API_KEY! });
const collection = await client.collections.create({
slug: 'contracts',
label: 'Contracts',
domain_keys: ['legal-ops'],
});
const collections = await client.collections.list();Get an API key from the dashboard under Settings → API Keys.
Error handling
Every failed request throws LiyaEngineAPIError — a real Error subclass carrying the API's code, message, and HTTP status:
import { LiyaEngineAPIError } from '@liyaengine/sdk';
try {
await client.collections.create({ slug: 'contracts', label: 'Contracts', domain_keys: ['legal-ops'] });
} catch (err) {
if (err instanceof LiyaEngineAPIError && err.code === 'SLUG_CONFLICT') {
// handle the conflict
}
throw err;
}Network failures and timeouts throw LiyaEngineNetworkError. Requests retry automatically on 429/5xx responses (2 retries by default).
Configuration
new LiyaEngine({
apiKey: 'liya_...',
baseUrl: 'https://api.liyaengine.ai', // override for local/staging
timeoutMs: 30_000,
maxRetries: 2,
});Collections
await client.collections.list();
await client.collections.get(id);
await client.collections.create({ slug, label, domain_keys });
await client.collections.update(id, { label, tags, visibility });
await client.collections.delete(id);Full field reference: Collections API.
Agents
await client.agents.list();
await client.agents.get(agentKey);
await client.agents.create({ agent_key, name, goal });
await client.agents.update(agentKey, { name, model });
await client.agents.deploy(agentKey); // activate for execution
await client.agents.run(agentKey, { input: { message } });
await client.agents.listRuns(agentKey);
await client.agents.listSessions(agentKey);
await client.agents.getTranscript(agentKey, sessionId);
await client.agents.delete(agentKey);Full field reference: Agents API.
Workflows
await client.workflows.list();
await client.workflows.get(workflowIdOrKey);
await client.workflows.create({ name, steps });
await client.workflows.update(workflowIdOrKey, { name, steps });
await client.workflows.toggle(workflowIdOrKey); // on/off, already-deployed only
await client.workflows.deploy(workflowIdOrKey); // draft -> active; mints webhook secret once
await client.workflows.rotateWebhookSecret(workflowIdOrKey, 300);
await client.workflows.run(workflowIdOrKey, { input: { email } });
await client.workflows.listRuns(workflowIdOrKey);
await client.workflows.delete(workflowIdOrKey); // hard deletedeploy() and rotateWebhookSecret() return the plaintext webhook secret exactly once — capture it from the response immediately. Full field reference: Workflows API.
Evaluations
A Suite binds a Dataset to one intent; suites.run() calls it for real. runs.submit()/evaluations.score() score a response you already generated yourself.
await client.evaluations.datasets.create({ name, cases });
await client.evaluations.suites.create({ name, domain_key, intent_key, dataset_id });
await client.evaluations.suites.run(suiteId); // 202, poll runs.get()
await client.evaluations.runs.get(runId);
await client.evaluations.runs.resume(runId); // only a failed run; already-scored cases are skipped
await client.evaluations.runs.compare(runIdA, runIdB); // statistical
await client.evaluations.score({ input, output }); // no dataset/suite requiredFull field reference: Evaluations API.