Alchemy resources
Every Maple resource the Alchemy provider manages: props, outputs and lifecycle for dashboards, alert rules, alert destinations, uptime monitors, status pages, API keys and ingest keys.
The resources @maple-dev/alchemy manages. New here? Start with the Alchemy quick start.
| Resource | Lifecycle | Main output |
|---|---|---|
Maple.Dashboard | Create, update in place, delete | dashboardId |
Maple.AlertDestination | Create, update in place, delete. Changing type replaces it | destinationId |
Maple.AlertRule | Create, update in place, delete. Ownership-tagged per stack | ruleId |
Maple.UptimeMonitor | Create, update in place, delete. Changing config.type replaces it | monitorId |
Maple.StatusPage | Create, update in place, delete | statusPageId |
Maple.ApiKey | Create, roll, revoke. Any other prop change replaces the key | secret |
Maple.IngestKeys | Read-only singleton | privateKey |
Props use the API’s snake_case wire shape, exactly as the interactive API reference documents the matching create endpoint. Outputs use camelCase.
Maple.Dashboard
Effect.gen(function* () {
const dash = yield* Maple.Dashboard("checkout", {
name: "Checkout",
description: "Golden signals for the checkout flow",
tags: ["checkout"],
time_range: { type: "relative", value: "12h" },
widgets: [/* widget documents */],
sections: [/* collapsible widget groups */],
variables: [/* dashboard variables */],
})
})
| Prop | Type | Notes |
|---|---|---|
name | string | Required |
description | string | null | |
tags | string[] | |
time_range | object | e.g. { type: "relative", value: "12h" } |
widgets | object[] | Typed by the API’s widget schema (Maple.DashboardWidget) |
sections | object[] | Widgets join one with section_id and tab_id; their layout is relative to the section’s grid |
variables | object[] | Typed by the API’s variable schema (Maple.DashboardVariable) |
refresh_interval_seconds | number | null | 0, 5, 10, 30, 60, 300 or 900 |
dashboardId | string | Adopt an existing dash_… dashboard instead of creating one. Cannot change after deploy |
Outputs: dashboardId (dash_…), name.
The easiest way to get a widget document is to build the dashboard in the UI and copy it from GET /v2/dashboards/{id}. See Build dashboards.
Maple.AlertDestination
A notification channel that alert rules deliver to. Props are discriminated on type:
type | Channel fields |
|---|---|
pagerduty | integration_key |
webhook | url, optional signing_secret |
discord | webhook_url |
telegram | bot_token, chat_id |
google-chat | webhook_url |
microsoft-teams | webhook_url (a Teams Workflows webhook) |
incident-io | alert_source_config_id, token |
email | member_user_ids (Maple user IDs in your org) |
linear | team_id (a team in the Linear workspace connected in Maple) |
Every variant also takes name (required) and enabled (defaults to true on both create and update).
Effect.gen(function* () {
const hooks = yield* Maple.AlertDestination("incident-webhook", {
type: "webhook",
name: "Incident bot",
url: "https://hooks.example.com/maple",
signing_secret: Redacted.make(process.env.WEBHOOK_SECRET!),
})
})
- Channel secrets (
integration_key,signing_secret,webhook_url,bot_token,token) are write-only: the API never returns them. Pass them asRedactedvalues so they stay out of logs and plan output. Because they cannot be read back, the provider re-sends them on every update. - Changing
typereplaces the destination with a new ID. - Slack and other chat-connector destinations depend on integrations linked in Maple, so manage them in Notification destinations, not here.
- Deleting a destination that rules still reference fails with a conflict. When the rules live in the same stack, Alchemy deletes them first.
Outputs: destinationId (dest_…), name, type, enabled, channelLabel (the non-secret channel handle, such as a Telegram chat ID, or null).
Maple.AlertRule
Effect.gen(function* () {
yield* Maple.AlertRule("api-p95", {
name: "API p95 latency",
severity: "warning",
signal_type: "p95_latency",
comparator: "gt",
threshold: 800,
window_minutes: 10,
service_names: ["api"],
consecutive_breaches_required: 2,
destination_ids: [oncall.destinationId],
})
})
| Prop | Type | Notes |
|---|---|---|
name | string | Required. Unique per organization |
severity | "warning" | "critical" | Required |
signal_type | AlertSignalType | Required. See values below |
comparator | AlertComparator | Required. See values below |
threshold | number | Required. Error rates are 0-1 ratios |
threshold_upper | number | Required for between / not_between, and only for them |
window_minutes | number | Required |
destination_ids | string[] | Required. dest_… IDs, usually destination.destinationId outputs |
enabled | boolean | |
notes | string | null | |
service_names | string[] | Only these services. Not with group_by |
exclude_service_names | string[] | All services except these. Needs group_by: ["service.name"] |
group_by | string[] | null | One incident per group. Not with service_names |
tags | string[] | Up to 19. alchemy: tags are reserved (see below) |
minimum_sample_count | number | |
consecutive_breaches_required | number | Breaching windows before it fires |
consecutive_healthy_required | number | Healthy windows before it resolves |
renotify_interval_minutes | number | |
alert_on_no_data | boolean | Count a window with no data as a breach. Not on grouped rules |
apdex_threshold_ms | number | null | For apdex rules |
query_builder_draft | object | Required for builder_query rules, passed through verbatim |
raw_query_sql | string | Required for raw_query rules |
raw_query_reducer | string | null | identity, sum, avg, min or max |
notification_template | object | null |
signal_type:error_rate,p95_latency,p99_latency,apdex,throughput,builder_query,raw_querycomparator:gt,gte,lt,lte,eq,neq,between,not_between
The props type refuses the combinations the API rejects, so they fail to type-check instead of failing the deploy: group_by and exclude_service_names only without service_names, and exclude_service_names only with group_by: ["service.name"]; query_builder_draft on builder_query only, which requires it; raw_query_sql and raw_query_reducer on raw_query only, which requires the SQL and reads no named services and no group_by; threshold_upper with between and not_between only, which require it; and no alert_on_no_data on a grouped rule. Every deploy sends service_names, exclude_service_names, group_by and alert_on_no_data, so removing one from props clears it. The API checks the rest, such as the SQL itself, and a failure there fails the deploy with a 400. See Alert rules for what each signal measures.
Outputs: ruleId (alrt_…), name, enabled.
Ownership
Each rule carries one alchemy:<hash> tag that identifies the stack, stage and logical resource that owns it. It uses one of Maple’s 20 tag slots, which is why tags is capped at 19. The tag is what makes state recovery safe:
- If Alchemy state is lost, the provider finds the rule by name and takes it back only when the ownership tag matches.
- A rule with the same name and no matching tag (created in the UI, or by another stack or stage) fails the deploy instead of being overwritten. To take it over deliberately, wrap the resource in Alchemy’s
adopt(true)or deploy with--adopt. - A stack never deletes a rule another stack has adopted.
Keep the ownership tag intact, and use distinct rule names for different stages that share one Maple organization.
Maple.UptimeMonitor
Effect.gen(function* () {
const api = yield* Maple.UptimeMonitor("api", {
name: "API health",
config: { type: "http", url: "https://api.example.com/health" },
interval_seconds: 60,
destination_ids: [oncall.destinationId],
})
})
| Prop | Type | Notes |
|---|---|---|
name | string | Required |
config | object | Required. type is http, tcp, dns, multistep or heartbeat; the rest as the API documents it |
interval_seconds | number | 30 to 3600. Unset keeps Maple’s |
failures_to_down | number | 1 to 10. Unset keeps Maple’s |
service_name | string | Attach the monitor to a service. Unset means none |
enabled | boolean | Defaults to true |
destination_ids | string[] | Notified when the monitor goes down or recovers. Unset means none |
Outputs: monitorId (upm_…), name, kind, heartbeatUrl (heartbeats: the URL your job pings), alertRuleId. See Uptime monitoring.
Maple.StatusPage
Effect.gen(function* () {
const api = yield* Maple.UptimeMonitor("api", {
name: "API health",
config: { type: "http", url: "https://api.example.com/health" },
})
const page = yield* Maple.StatusPage("status", {
name: "Acme Status",
slug: "acme-status",
support_url: "https://acme.example/support",
theme: { preset: "midnight", accent: "#a5b4fc" },
components: [
{ name: "API", monitor_id: api.monitorId },
{ name: "Docs", group: "Websites", show_uptime: false },
],
custom_domain: "status.acme.example",
})
// page.customDomain.dnsRecords: the records to create at your DNS provider
})
The props are the page’s config document (PUT /), plus password and custom_domain:
| Prop | Type | Notes |
|---|---|---|
name, slug | string | Required. The page is served at < |
description, website_url, support_url, privacy_url, terms_url | string | null | Page text and links |
logo_url, logo_dark_url, favicon_url | string | null | An https URL, or a base64 data:image/... URL of at most 128 KB |
show_powered_by | boolean | Defaults to true |
auto_incidents | "off" | "draft" | "publish" | Defaults to off |
visibility | "public" | "password" | "internal" | Unset keeps the page’s (public for a new page) |
theme | object | preset, appearance, accent, background, text, card, border, radius, font. Unset fields take the default theme |
components | object[] | In display order: name, description, group, monitor_id, manual_status, show_uptime |
password | string | Redacted | Needed for visibility: "password". Write-only to Maple, but kept in Alchemy state: protect the state as a credential |
custom_domain | string | Also serve the page on this hostname. Not allowed on an internal page |
- Components are matched to the page’s existing ones by name, so their IDs, incidents and uptime history survive reordering and edits. Renaming a component recreates it; leaving one out deletes it.
- Leave
manual_statusunset and an override a responder sets during an incident stays; a deploy does not undo it.nullclears it. passwordandcustom_domainare only managed once declared: removing the prop removes the password or domain.- A new page is published once it is fully configured, so a half-made page is never served.
Outputs: statusPageId (stp_…), name, slug, components ({ componentId, name }[], for incidents posted through the API), customDomain ({ hostname, cnameTarget, dnsRecords } or null), configVersion. Incidents are operational and are not declared here. See Status pages.
Maple.ApiKey
Effect.gen(function* () {
const ci = yield* Maple.ApiKey("ci", {
name: "ci-pipeline",
scopes: ["dashboards:write", "alerts:read"],
rotate: 1,
})
// ci.secret is a Redacted<string>; bind it into another resource's env.
})
| Prop | Type | Notes |
|---|---|---|
name | string | Required |
description | string | |
scopes | string[] | Omit for full access |
kind | "standard" | "mcp" | Defaults to standard. mcp keys only work on the MCP server |
expires_in_seconds | number | |
rotate | number | string | Bump it (1 to 2) to roll the key |
The API has no update endpoint for keys:
- Changing
name,description,scopes,kindorexpires_in_secondsreplaces the key: a new ID and a new secret, and the old key is revoked. - Bumping
rotaterolls the key: Maple revokes the old key and issues a replacement with the same name, description, kind and scopes, a newkeyIdand a new secret. - Deleting the resource revokes the key.
Outputs: keyId (key_…), name, keyPrefix, secret (Redacted, the full maple_ak_… value).
The API returns a secret only once, at create or roll time. The provider stores it in Alchemy state, which is the only place it survives, so keep your state somewhere durable and encrypted.
Maple.IngestKeys
Effect.gen(function* () {
const ingest = yield* Maple.IngestKeys("ingest")
// ingest.publicKey -> maple_pk_… for browser and mobile senders
// ingest.privateKey -> maple_sk_… for server-side senders
})
A read-only view of your organization’s ingest keys. It takes no props, and there is one per organization. Deleting the resource only stops tracking it; the keys stay valid. Rolling is not modeled, because a roll immediately invalidates the old key for every sender. Roll ingest keys from Settings → Ingestion instead.
Outputs: publicKey, privateKey (both Redacted), publicRotatedAt, privateRotatedAt.
Drift and sync
- A deploy compares declared props against what the API returns and patches only when they differ. Fields you leave out of props stay unmanaged, so edits to them in the UI are kept. An uptime monitor manages
service_name,enabledanddestination_idseven when unset (none,true, none). A status page is the exception: it is applied as a whole document, so unset fields take their defaults and a component added in the UI is deleted. Only an unsetmanual_statuson a declared component, avisibilityleft unset, and apasswordorcustom_domainthe stack never declared, are left alone; removing a declaredpasswordorcustom_domainremoves it. alchemy syncrestores declared dashboard fields, alert rule configuration and status pages to what the stack declares.- Alert destination secrets cannot be compared, so drift in them is only caught when you change the prop.
Errors and retries
The client retries 429 and 5xx responses with bounded exponential backoff and honors retry_after_seconds from the error envelope. The API allows 600 requests per 60 seconds per key, which a large stack stays well under.
Failures surface as typed errors in Effect’s error channel. An API failure is tagged with the server’s own @maple/http/… error tag and carries the HTTP status and the error body (type, code, message); Maple.MapleErrorTags has the tags to catchTag on. Client-side failures are MapleApiTransportError, MapleApiResponseDecodeError, MapleApiProtocolError and MapleApiRequestEncodingError. Rule ownership conflicts are MapleAlertRuleOwnershipError, and invalid or reserved rule tags are MapleAlertRuleTagsError.