Using the StackGen SDK

Install a language package, construct a client with an explicit config, then call product namespaces (aiden, sre, vault).

Aiden automation (webhooks, Ask, sessions, artifacts): read the full guide with glossary and step-by-step samples in AIDEN-GUIDE.md.

Prefer explicit StackgenConfig in application code. Do not rely on a large set of environment variables for production runs.

Shared credentials

Webhook trigger credentials (webhook_token) are config fields, not default env vars — pass them when you call webhook helpers.

Python

pip install stackgen-sdk==0.1.5

from pathlib import Path
from stackgen import StackgenClient, StackgenConfig

client = StackgenClient(
    StackgenConfig(
        base_url="https://app.stackgen.com",
        api_token="stackgen_…",
        org_id="<project-uuid>",
        webhook_token="sg_aios_…",  # only needed for webhook journeys
    )
)

# Aiden: trigger webhook → wait → download session-report.md
result = client.aiden.run_webhook_and_download_report(
    Path("alert.json").read_text(encoding="utf-8")
)
print(result.session_id, result.output_path)

# Aiden: Ask Guild → poll execution → download artifact (API token only)
ask = client.aiden.run_ask_and_download_artifact(
    message="Run triage for checkout CPU alert",
    entity_refs=[{"name": "incident-triage", "type": "workflow"}],
    artifact_name="session-report.md",
)
print(ask.trace_id, ask.session_id, ask.output_path)

# SRE
alerts = client.sre.list_alerts()
alert = client.sre.get_alert("<alert-id>")
started = client.sre.investigate_alert(alert["id"])
inv = client.sre.get_investigation(started["investigation"]["id"])

Optional convenience — load only the three default env vars, then set the rest in code:

from dataclasses import replace
from stackgen import StackgenClient, StackgenConfig

client = StackgenClient(
    replace(
        StackgenConfig.from_env(),  # STACKGEN_URL, STACKGEN_TOKEN, STACKGEN_PROJECT
        webhook_token="sg_aios_…",
    )
)

Import name is stackgen (distribution name is stackgen-sdk).

TypeScript / JavaScript

npm install stackgen-sdk@0.1.5

import { readFileSync } from "node:fs";
import { StackgenClient, StackgenConfig } from "stackgen-sdk";

const client = new StackgenClient(
  new StackgenConfig({
    baseUrl: "https://app.stackgen.com",
    apiToken: "stackgen_…",
    orgId: "<project-uuid>",
    webhookToken: "sg_aios_…", // only needed for webhook journeys
  }),
);

const result = await client.aiden.runWebhookAndDownloadReport(
  readFileSync("alert.json", "utf8"),
);
console.log(result.sessionId, result.outputPath);

const ask = await client.aiden.runAskAndDownloadArtifact({
  message: "Run triage for checkout CPU alert",
  entityRefs: [{ name: "incident-triage", type: "workflow" }],
  artifactName: "session-report.md",
});
console.log(ask.traceId, ask.sessionId, ask.outputPath);

const alerts = await client.sre.listAlerts();

Optional convenience — load only the three default env vars, then set the rest in code:

const base = StackgenConfig.fromEnv(); // STACKGEN_URL, STACKGEN_TOKEN, STACKGEN_PROJECT
const client = new StackgenClient(
  new StackgenConfig({
    baseUrl: base.baseUrl,
    apiToken: base.apiToken,
    orgId: base.orgId,
    webhookToken: "sg_aios_…",
  }),
);

Requires Node.js 18+. Network methods are async.

Namespaces

Errors

• StackgenError — base type
• HttpError — HTTP failure (statusCode when available)
• TimeoutError — poll/wait exceeded timeout_seconds
• NotAllowlistedError — operation not included in this SDK release

GET poll/download retries on 429 / 502 / 503 / 504.

Versions

Pin releases in CI (pip install stackgen-sdk==0.1.5, npm install stackgen-sdk@0.1.5). See the Product map for the API surface in each release.

For webhook triggers, Ask Guild, waiting for session_id, and downloading session-report.md, see AIDEN-GUIDE.md (glossary + Python/TypeScript examples).

For Ask + SRE side by side, see Automation surface. For investigate-from-alert, see SRE → investigate alert.

See FAQ for installation, authentication, webhook setup, error handling, report consumption, and operational limits.