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/... |
| Vault | client.vault |
/vault/v1/... |
Install (Python): pip install stackgen-sdk → StackgenClient
Go module: github.com/appcd-dev/stackgen-sdk/clients/go
Public API surface (this release)
The SDK exposes a curated subset of StackGen HTTP APIs — the operations below are
what you can call from client.aiden, client.sre, and client.vault. If an
operation is not listed, it is not available in this SDK version (NotAllowlistedError).
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 |
startAskGuild |
Start Ask Guild with a message (optionally pin workflow via entity_refs) |
getExecutionTrace |
Poll Ask execution until settled |
listExecutions |
List recent executions (filter by session_id) |
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 |
Create or update an agent (used by publishWorkflow) |
getWorkflow / createWorkflow / updateWorkflow |
Read or write workflow drafts |
createWorkflowVersion / updateWorkflowVersion / approveWorkflowVersion |
Version + approve so a workflow can run |
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.
Stateless run control (for queue + scheduler architectures): trigger_webhook,
get_webhook_run, list_webhook_runs, wait_for_webhook_session, get_execution_trace,
list_executions, list_sessions, get_session, list_session_artifacts, download_session_artifact,
export_session, terminate_session. See
Async webhook CI 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 |
Vault (client.vault)
No operations in v0.1.5. Vault APIs may be added in a future release.
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 |
| Org | UUID | orgId query on Aiden |
Journeys
See AIDEN-GUIDE.md 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→ pollget_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,502,503,504) 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.