TypeScript SDK

@siloga/magmell is a zero-runtime-dependency TypeScript client built on the global fetch API. It uses camel-case application types while mapping explicitly to the gateway’s wire format.

Create a client

Use an API key in a server or CI process:

import { MagmellClient } from '@siloga/magmell'

const magmell = new MagmellClient({
  baseUrl: 'https://api.magmell.siloga.cloud',
  apiKey: process.env.MAGMELL_API_KEY,
})

Never place an API key in public browser code. Browser operator tools should authenticate a user and pass accessToken, teamId, and a refresh callback.

Deploy code

From a Node.js directory:

const deployment = await magmell.deploy({
  name: 'reviewer',
  version: '1',
  dir: './agents/reviewer',
  requirements: ['httpx==0.28.1'],
  setupSteps: ['apt-get update', 'apt-get install -y ffmpeg'],
})

await magmell.waitForBuild(deployment.deploymentId)

Or provide an explicit filename-to-source map:

await magmell.deploy({
  name: 'greeter',
  version: '1',
  code: {
    'handler.py': 'def handle(input):\n    return {"hello": input.get("name")}\n',
  },
})

Run and await a result

const created = await magmell.runByName(
  'reviewer',
  { document: 'Text to review' },
  { version: '1', timeoutS: 120 },
)

const completed = await magmell.waitForRun(created.runId)

if (completed.status === 'failed') {
  throw new Error(completed.error ?? 'agent run failed')
}

console.log(completed.result)

The waiting helpers default to a five-minute deadline and two-second polling interval. Override them when your application has different latency expectations.

Paginate collections

let cursor: string | undefined

do {
  const page = await magmell.listRuns({ limit: 50, cursor })
  for (const run of page.items) console.log(run.runId, run.status)
  cursor = page.nextCursor ?? undefined
} while (cursor)

Do not construct or interpret pagination cursors yourself; treat them as opaque values.

Select exact versions

const deployment = await magmell.getDeploymentByName('reviewer', { version: '2' })

await magmell.putSecretsByName(
  'reviewer',
  { MODEL_API_KEY: process.env.MODEL_API_KEY! },
  { version: '2' },
)

await magmell.runByName('reviewer', input, { version: '2' })

Carry the version through every version-sensitive operation during a rollout.

Handle errors

import { MagmellError } from '@siloga/magmell'

try {
  await magmell.getRun(runId)
} catch (error) {
  if (error instanceof MagmellError) {
    console.error(error.status, error.message, error.body)
  }
  throw error
}

MagmellError.status contains the HTTP status for request failures. Waiting failures and timeouts use status 0 because they are client-side operational errors rather than HTTP responses.

Main method groups

Area	Methods
Deployments	`deploy`, `getDeployment`, `getDeploymentByName`, `listDeployments`, `deleteDeployment`, `waitForBuild`
Runs	`run`, `runByName`, `getRun`, `getRunByNumber`, `listRuns`, `listRunsByName`, `waitForRun`
Events	`getRunEvents`, `getRunEventsByNumber`
Secrets	`putSecrets`, `putSecretsByName`, `getSecretNames`, `getSecretNamesByName`
Keys	`createKey`, `listKeys`, `revokeKey`
Teams	`me`, membership management methods, `setTeamId`