StackGen Product API

Language-neutral documentation for the StackGen SDK.

One product

Customer term	Client access	HTTP prefix
Aiden	`client.aiden`	`/guild/api/v1/...`
SRE	`client.sre`	`/app/sre/...`
DevOps	`client.devops`	`/app/devops/...`
Vault	`client.vault`	`/api/vault/v1/...`
Context Graph	`client.contextGraph` / `context_graph` / `ContextGraph`	`/context-graph/...`

Install: pip install stackgen-sdk → StackgenClient · npm install stackgen-sdk · go get github.com/appcd-dev/stackgen-sdk/clients/go → stackgen.NewClient (Go is invite-only while the repository is private; ask StackGen for access)

Public API surface (this release)

Upstream OpenAPI catalogs are larger than this SDK. We expose a curated surface: allowlisted ops for codegen, plus journey helpers that stitch them into something useful. Prefer the helpers (run_webhook_and_download_report, wait_for_subscribe_complete, …) over calling every low-level op yourself. If an operation is not allowlisted, it is not available (NotAllowlistedError).

SDK methods lists each helper on client.aiden, client.sre, client.devops, client.vault, and client.contextGraph, with the Python, TypeScript, and Go name on one row (Go rows hide when a helper is not ported yet).

OpenAPI (Swagger) YAML: Download stackgen.openapi.yaml — same allowlisted surface the SDK clients are generated from. Import it into Postman, Insomnia, or any OpenAPI tooling.

Aiden (`client.aiden`)

Operation	Typical use
`triggerWebhook`	POST alert or payload to start a workflow
`listWebhookRuns` / `getWebhookRun`	Poll until `session_id` is available
`startAsk`	Start Ask with a message (optionally pin workflow via `entity_refs`)
`getExecutionTrace`	Poll Ask execution until settled
`listExecutions`	List recent executions (filter by `session_id`)
`exportExecutionDebugBundle`	Download the execution debug ZIP (Activity / watch export)
`getSessionByID` / `listSessions`	Read one session or search sessions
`listSessionArtifacts` / `downloadSessionArtifact`	Wait for and download reports
`exportSession`	Fetch report/notes/evidence when no artifact file is present
`terminateSession`	Cancel running work for a session (scheduler timeout)
`registerAgent` / `updateAgent` / `getAgent` / `deregisterAgent` / `getAgentHealth`	Agent lifecycle
`createWebhook` / `getWebhook` / `updateWebhook` / `deleteWebhook`	Webhook CRUD (plus trigger / runs). Create/update accept optional `response_status` / `response_headers` for provider acknowledgements and an optional `filter_cel` condition
`previewWebhookFilter`	Try a draft `filter_cel` condition against a sample event/headers; saves nothing and starts no work
`createSchedule` / `triggerSchedule` / `listScheduleRuns` / `deleteSchedule`	Schedule automation
`listIntegrations` / `getIntegration` / `upsertIntegration` / …	Integration catalog (`getIntegration` defaults to `include_tools`)
`upsertIntegrationWithSecrets`	Plain secrets map → Vault metadata resolve → store + `secret_ref_ids` bind + upsert
`listApprovals` / `getApproval` / `resolveApproval`	HITL approvals
`createPolicy` / `attachPolicy` / `evaluatePolicy` / …	Runtime policies (attach supports shadow dry-run)
`breakGlass` / `getBreakGlass` / `endBreakGlass`	Time-limited outage bypass; `activated_by` on the response from API token
`whenPoliciesDisagree`	Tie-break when several attached policies conflict
`listAuditEvents` / `getAuditEvent` / `listAuditFacets`	Audit read (first page / by id / facets)
`iterAuditEvents` / `exportAuditEvents`	Page past the cursor cap; write NDJSON (optional `format: "ocsf"`)
`subscribeExecution` / `listExecutionToolCalls` / `forkSession`	Execution stream + fork
`listAgents` / `listWorkflows`	Agent and workflow names for a chat target picker
`runWorkflow` / `deleteWorkflow` / knowledge / skills / remote-runner admin	Extended product surface
`getWorkflow` / `createWorkflow` / `updateWorkflow`	Read or write workflow drafts
`createWorkflowVersion` / `updateWorkflowVersion` / `approveWorkflowVersion`	Version + approve so a workflow can run

See api-docs/product/allowlists/external.yaml for the full allowlisted operationId list.

High-level helpers: create_agent / create_stage / create_workflow + publish_workflow, run_webhook_and_download_report, run_ask_and_download_artifact, start_ask + wait_for_execution + wait_for_subscribe_complete, stream_execution_events / streamExecutionEvents (live AG-UI chat events), iter_audit_events / export_audit_events.

Stateless run control (for queue + scheduler architectures): trigger_webhook, get_webhook_run, list_webhook_runs, wait_for_webhook_session, get_execution_trace, list_executions, download_execution_debug_zip, list_sessions, get_session, list_session_artifacts, download_session_artifact, export_session, terminate_session. See Async webhook CI, Ask → debug ZIP, and Automation surface.

SRE (`client.sre`)

Operation	Typical use
`listAlerts` / `getAlertV1`	List or fetch alerts
`investigateAlert`	Start an investigation from an alert
`listInvestigations` / `getInvestigation`	Track investigation status and RCA

See SRE → investigate alert.

Vault (`client.vault`)

Operation / helper	Typical use
`storeSecret` / `store_secret`	Store a secret (raw body)
`getSupportedMetadata` / `get_supported_metadata`	Typed Vault category/subcategory key catalog (`VaultSupportedFormat`)
`storeGithubSecret` / `storeGrafanaSecret` / `storeKafkaSecret` / `storeGenericSecret`	Category helpers for common integration credentials
`getSecret` / `listSecrets` / `updateSecret` / `deleteSecret`	Read, list, update, delete by id

Prefer aiden.upsertIntegrationWithSecrets when the goal is a working integration. Use these Vault helpers when you already manage secret lifecycle separately. Schemas are sliced only from infraops/api-specs/stackgen-vault (never from vendored copies). Sample: Integration secrets → agent → Ask.

Context Graph (`client.contextGraph`)

Operation / helper	Typical use
`health` / `ready`	Liveness and readiness probes (deliberately minimal)
`getWorkspaceStatus`	Readiness + record counts + per-connector sync health in one call
`listRecordTypes` / `getRecord` / `queryRecords`	Inventory and graph queries
`getSchema` / `getSchemaType`	Type catalog for clients and agents
`listConnectors` / `listConnectorSources` / `listConnectorSchedules` / `setConnectorScheduleInterval`	Connector catalog
`startConnectorSync` / `getConnectorSync` / `listConnectorSyncs` / `syncAndWait`	Start a sync and poll until it settles
`listEntityLinkRules`	Entity link rules for the workspace
`searchGraphTools`	Search graph tools by query string or body

Default HTTP prefix is ${STACKGEN_URL}/context-graph. Override with contextGraphUrl / context_graph_url / ContextGraphURL for local or port-forward runs. Sample: Context Graph inventory.

Base URL for all calls: https://app.stackgen.com (override per environment in StackgenConfig.base_url).

Auth

Token	Format	Use
API token	`stackgen_…`	Sessions, artifacts, SRE, Vault
Webhook token	`sg_aios_…`	Aiden `triggerWebhook` only
Workspace	UUID	`workspaceId` / `workspace_id`; sent as `orgId` on Aiden

Journeys

See the Aiden guide for glossary, flow diagrams, and Python/TypeScript samples.

Create a workflow — create_workflow(…).then(…).commit() + client.aiden.publish_workflow(…) (sample)
Webhook → report — client.aiden.run_webhook_and_download_report(payload)
Ask → report — client.aiden.run_ask_and_download_artifact(message, entity_refs=…) (API token only; poll-based)
SRE investigate alert — list_alerts → investigate_alert → poll get_investigation (sample)
Automation overview — Ask + SRE side by side (sample)

Runnable samples: Code samples (full scripts inline on this site).

Errors and retries

Python raises StackgenError
Transient GET failures (429 and any 5xx) retry with backoff
Trigger POST is not blindly retried

Ops / limits

Default poll timeout 30 minutes
App-forward webhooks are not covered by the wait/download journey

See FAQ for installation, auth, retries, report consumption, and SRE operational notes.