Server examples

These examples target the proposed HTTP contract. No published SDK package or live origin is assumed. Keep credentials in your server environment. Use the IDs and verified API origin supplied by the console after approval.

TypeScript / Node.js 22

The pilot's planned server TypeScript SDK will expose typed resources, bounded read retries, SSE parsing, and webhook verification. Until its release is verified, use standard fetch as below. Browser service-key execution is unsupported.

import { randomUUID } from 'node:crypto';
const base = process.env.MYSTRO_BASE_URL ?? 'https://api.mystro.invalid';
const tenant = process.env.MYSTRO_TENANT_ID!;
const key = process.env.MYSTRO_API_KEY!;
const scope = `${base}/v1/tenants/${encodeURIComponent(tenant)}/environments/sandbox`;

async function call(path: string, body?: unknown, idempotencyKey?: string) {
  const response = await fetch(scope + path, {
    method: body === undefined ? 'GET' : 'POST',
    headers: {
      Authorization: `Bearer ${key}`,
      ...(body === undefined ? {} : {
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey!,
      }),
    },
    body: body === undefined ? undefined : JSON.stringify(body),
  });
  const result = await response.json();
  if (!response.ok) throw new Error(`${result.error?.code}: ${result.request_id}`);
  return result;
}

// Persist these intent IDs before sending, and reuse them after network failure.
const conversationIntent = randomUUID();
const runIntent = randomUUID();
const { data: conversation } = await call('/conversations', {
  workspace_id: process.env.MYSTRO_WORKSPACE_ID!,
  agent_revision_id: process.env.MYSTRO_AGENT_REVISION_ID!,
}, conversationIntent);
const { data: run } = await call(`/conversations/${conversation.id}/runs`, {
  input: [{ type: 'text', text: 'Summarize the supplied operations notes.' }],
}, runIntent);
// Store run.id. Poll or consume SSE; acceptance is not completion.
const current = await call(`/runs/${run.id}`);
console.log({ run_id: current.data.id, status: current.data.status });

On an HTTP error, show the safe error code and request ID. Do not log headers or raw responses from secret-issuance operations. This minimal example deliberately leaves durable application storage and polling to your app.

Python 3 standard library

Python uses the same HTTP contract; a separate Python SDK is deferred.

import json, os, uuid
from urllib.request import Request, urlopen
from urllib.parse import quote
from urllib.error import HTTPError

base = os.getenv('MYSTRO_BASE_URL', 'https://api.mystro.invalid')
tenant = quote(os.environ['MYSTRO_TENANT_ID'], safe='')
scope = f'{base}/v1/tenants/{tenant}/environments/sandbox'

def call(path, body=None, intent=None):
    headers = {'Authorization': 'Bearer ' + os.environ['MYSTRO_API_KEY']}
    if body is not None:
        headers.update({'Content-Type': 'application/json', 'Idempotency-Key': intent})
    request = Request(scope + path, headers=headers,
                      data=None if body is None else json.dumps(body).encode(),
                      method='GET' if body is None else 'POST')
    try:
        with urlopen(request, timeout=20) as response:
            return json.load(response)
    except HTTPError as error:
        result = json.load(error)
        raise RuntimeError(f"{result['error']['code']}: {result['request_id']}") from None

# Persist these IDs with your application's work record before dispatch.
conversation_intent, run_intent = str(uuid.uuid4()), str(uuid.uuid4())
conversation = call('/conversations', {
    'workspace_id': os.environ['MYSTRO_WORKSPACE_ID'],
    'agent_revision_id': os.environ['MYSTRO_AGENT_REVISION_ID'],
}, conversation_intent)['data']
run = call(f"/conversations/{conversation['id']}/runs", {
    'input': [{'type': 'text', 'text': 'Summarize the supplied operations notes.'}],
}, run_intent)['data']
print({'run_id': run['id'], 'status': run['status']})

cURL and the full workflow

The first-run guide contains copyable cURL commands. For an end-user workflow, follow ticket tools and approval integration; do not use the ordinary sandbox service actor to approve a write.

Private server SDK build

The repository contains a buildable private ESM server SDK with declarations. It is not published to npm. Node 22 or later is required; use it only in your backend with a verified API origin. Its helpers cover agent/revision configuration, user/workspace provisioning, actor sessions, conversations/runs/events, connections/tools/approvals, files, webhooks, key list/revoke, and date-bounded own-actor usage. It does not create or rotate service keys.

The support-ticket integration example uses a customer-owned HTTP handler and SQLite transaction for the note and operation receipt. It validates Ed25519 signatures against trusted public JWKS, issuer/audience, tenant/environment/generation, actor business permissions, and exact human approval. A lost write response is reconciled through the stored operation receipt. Synthetic integration tests do not establish live public API availability.