# Alfred Documentation

Alfred is a Bun + Hono API for durable infrastructure workflows.
Use /llms-full.txt for the full authored documentation corpus.
Use /openapi.json for the generated OpenAPI 3.1 client contract.
Use /openapi.operator.json for the generated OpenAPI 3.1 operator contract.

## Pages
- [Alfred Documentation](/docs): Integrate with Alfred's durable workflow API and operate the service safely.
- [Deployment And Operations](/docs/explanation/deployment-and-operations): Understand Alfred's Railway topology, readiness, reconciliation, observability, and local AWS emulation.
- [Execution Lifecycle](/docs/explanation/execution-model): Follow workflow identity, serialization, durable execution, continuation, and terminal outcomes.
- [Provider Workflows And Rollback](/docs/explanation/provider-workflows-and-rollback): Understand domain and certificate provider flows, preservation boundaries, mutation receipts, and compensation.
- [Runtime Architecture](/docs/explanation/runtime-architecture): Understand Alfred's processes, durable state, transient delivery, and provider adapters.
- [System Context](/docs/explanation/system-overview): See Alfred's scope, actors, external systems, and capability boundary.
- [Consume Events](/docs/how-to/consume-events): Read execution history, connect to SSE, or subscribe to signed webhooks.
- [Monitor and Control Executions](/docs/how-to/monitor-and-control): Query execution state, stream progress, and apply supported controls.
- [Recover Workflows](/docs/how-to/recover-workflows): Continue, retry finalization, or roll back a supported failed workflow.
- [Use Alfred in Slack](/docs/how-to/use-alfred-in-slack): Start guided Alfred workflows from Slack and follow their progress in the operations channel.
- [Authentication Reference](/docs/reference/authentication): Bearer authentication, API key behavior, permissions, and common authorization errors.
- [Service Capabilities](/docs/reference/capabilities): Current client workflows, contract boundaries, configuration gates, and readiness coverage.
- [Environment Reference](/docs/reference/environment): Client variables, production runtime configuration groups, and Slack settings.
- [Event Reference](/docs/reference/events): Event envelopes, active event types, catalog schemas, and delivery semantics.
- [Execution Reference](/docs/reference/executions): Execution fields, statuses, stage records, filters, and control routes.
- [LLM Documentation](/docs/reference/llms): Machine-readable documentation routes generated from the current Fumadocs site.
- [Workflow Reference](/docs/reference/workflows): Supported workflow triggers, request behavior, permissions, and durable stages.
- [Run Your First Workflow](/docs/tutorials/first-workflow): Authenticate, submit an add-certificate dry run, and inspect its execution.
- [API Reference](/docs/reference/api): Generated OpenAPI operations and schemas for the Alfred API.
- [Event catalog](/docs/reference/api/eventCatalog): Public, read-only catalog of Alfred event types, lifecycle metadata, and JSON Schemas; it requires no bearer token and does not depend on workflow state.
- [List executions](/docs/reference/api/listExecutions): Read-only execution search for an authenticated principal. Results are limited to workflows for which the caller has workflows:<name> entitlement, then filtered by workflow, status, requesting principal, and limit; no execution state is changed.
- [Get execution](/docs/reference/api/getExecution): Reads one execution, its ordered stages, and any normalized onboarding outcome. The bearer principal must hold the workflows:<name> entitlement corresponding to that execution; the operation is valid in every execution state and does not mutate it.
- [Cancel non-terminal execution](/docs/reference/api/cancelExecution): Requires the workflows:<name> entitlement for the execution and mutates only cancelable, non-terminal work. Lambda updates record a cancellation request, while other workflows cancel their run and execution; add-subdomain cannot be canceled after Route 53 has accepted its change.
- [Queue execution rollback](/docs/reference/api/rollbackExecution): Requires the workflows:<name> entitlement for the execution. The mutating action queues receipt-backed rollback for a source workflow run, while a failed or canceled execution without a source run is marked rolled back immediately; Lambda restoration additionally requires a terminal execution with durable receipts.
- [Retry add-certificate finalization](/docs/reference/api/retryExecutionFinalization): Requires the workflows:add-certificate or workflows:onboard-domain entitlement matching the execution. This mutating recovery queues finalization only for a failed execution at its finalization stage with a source run and successful persisted prerequisite outputs; duplicate pending recovery is reused.
- [Retry Google Maps referrer whitelisting](/docs/reference/api/retryGoogleMapsWhitelist): Requires workflows:onboard-domain for the execution. This mutating recovery queues only for a succeeded onboarding run whose Google Maps stage records manual-required; an existing pending retry is returned instead of creating another command.
- [Resume failed or paused execution](/docs/reference/api/resumeExecution): Requires the workflows:<name> entitlement for the execution. The mutating action resumes a paused run that owns its active command lane, or queues an eligible failed or canceled update-lambda-version retry; other states and unsupported failed or canceled workflows are rejected.
- [Read execution events](/docs/reference/api/executionEvents): Reads events for an execution after checking the workflows:<name> entitlement associated with it. Available in every execution state, it returns ordered persisted events as JSON or opens an SSE feed when Accept requests text/event-stream; it does not mutate the execution.
- [Stream events over SSE](/docs/reference/api/streamEvents): Opens a read-only SSE stream using a bearer credential or one-time short-lived stream token. At least one workflow entitlement is required, requested workflow filters are narrowed to those entitlements, and the stream does not depend on or mutate execution state.
- [Create short-lived stream token](/docs/reference/api/createStreamToken): Mints a single-use, five-minute stream token for an authenticated principal with at least one workflow entitlement. This mutates token storage but no execution state; the token can authenticate GET /v1/streams/events without exposing the API key in its URL.
- [List webhook subscriptions](/docs/reference/api/listSubscriptions): Requires subscriptions:manage and lists only webhook subscriptions owned by the authenticated principal. This read-only operation accepts a limit from 1 to 100.
- [Create webhook subscription](/docs/reference/api/createSubscription): Requires subscriptions:manage. Registers the authenticated principal's public HTTPS callback after URL safety validation, encrypts the shared secret without returning it, and responds with the new subscription.
- [Get webhook subscription](/docs/reference/api/getSubscription): Requires subscriptions:manage and returns one webhook subscription only when it belongs to the authenticated principal. Secret material is never exposed.
- [Update webhook subscription](/docs/reference/api/updateSubscription): Requires subscriptions:manage and owner access. Updates the active flag, event filters, or both; callback URLs and signing secrets are changed through other lifecycle operations.
- [Disable webhook subscription](/docs/reference/api/deleteSubscription): Requires subscriptions:manage and owner access. Disables the webhook subscription instead of deleting its history, then returns an empty response.
- [List delivery attempts](/docs/reference/api/listSubscriptionDeliveries): Requires subscriptions:manage and lists recent delivery attempts for a webhook subscription owned by the authenticated principal. This read-only operation accepts a limit from 1 to 100.
- [Redeliver event](/docs/reference/api/redeliverSubscriptionEvent): Requires subscriptions:manage and owner access. Queues another delivery attempt for the selected subscription event and returns the pending attempt immediately.
- [Rotate signing secret](/docs/reference/api/rotateSubscriptionSecret): Requires subscriptions:manage and owner access. Encrypts and replaces the webhook signing secret, records an audit decision, and never returns secret material.
- [Trigger onboard-domain](/docs/reference/api/triggerOnboardDomain): Onboards one primary domain through registration, certificate and routing setup, Google Maps whitelisting, and completion. The request schema trims and lowercases domain, applies certificate option defaults, and normalizes ticket IDs. Required permission: workflows:onboard-domain. A new request is accepted for asynchronous Workflow SDK execution; use the returned execution ID with GET /v1/executions/{id} to track it.
- [Trigger add-certificate](/docs/reference/api/triggerAddCertificate): Creates or adopts certificate infrastructure for one or more comma-separated domains. The request schema removes spaces, lowercases domains, applies option defaults, and deduplicates ticket IDs. Required permission: workflows:add-certificate. A new request is accepted for asynchronous Workflow SDK execution; use the returned execution ID with GET /v1/executions/{id} to track it.
- [Trigger add-domain](/docs/reference/api/triggerAddDomain): Registers a root/apex domain by finding or creating its Route 53 hosted zone and, when needed, updating GoDaddy nameservers. Send a bare apex domain such as example.com in domainString, without a protocol, path, wildcard, or leading www; the request schema otherwise passes the string through unchanged. Required permission: workflows:add-domain. A new request is accepted for asynchronous Workflow SDK execution; use the returned execution ID with GET /v1/executions/{id} to track it.
- [Trigger add-subdomain](/docs/reference/api/triggerAddSubdomain): Plans and applies Route 53 records for labels relative to rootDomain, pausing for approval before replacing existing records. The request schema trims and lowercases DNS names, removes a final dot, and deduplicates labels; values such as blog and offers.eu are relative labels, not full names under the root. Required permission: workflows:add-subdomain. A new request is accepted for asynchronous Workflow SDK execution; use the returned execution ID with GET /v1/executions/{id} to track it.
- [Trigger update-lambda-version](/docs/reference/api/triggerUpdateLambdaVersion): Plans and updates the selected Lambda@Edge fleet to a positive integer version in the requested environment. The strict request schema applies the dry-run default and rejects unsupported target/environment pairs. Required permission: workflows:update-lambda-version. A new request is accepted for asynchronous Workflow SDK execution; use the returned execution ID with GET /v1/executions/{id} to track it. Fleet and provider work continues durably after this request is accepted; stable asynchronous failures are reported on the execution and its events. Request cancellation at /v1/executions/{id}/cancel, retry unfinished work at /v1/executions/{id}/resume, and restore receipt-backed changes at /v1/executions/{id}/rollback.
- [Get the persisted add-subdomain DNS plan](/docs/reference/api/getExecutionSubdomainPlan): Reads the persisted DNS plan after checking the workflows:add-subdomain entitlement for the execution. The operation is read-only and succeeds only for an add-subdomain execution with a valid plan already produced; other workflow or planning states return a conflict.
- [Approve an add-subdomain replacement plan](/docs/reference/api/approveExecutionSubdomainPlan): Requires the workflows:add-subdomain entitlement for the execution and mutates a paused workflow by resuming its approval hook. The execution must be waiting for replacement approval of the submitted current plan hash; an already accepted approval is replayed safely.

## Generated APIs
- [Client OpenAPI JSON](/openapi.json)
- [Operator OpenAPI JSON](/openapi.operator.json)