REST API reference

Returns the organisation, the member this key speaks as, its scopes, its capability flags, and, for an agent key, its budget and expiry. Call this first: a key resolves to a member and cannot exceed what that member can do, so this tells you your real ceiling before you plan anything.

Scopes

product:read

Returns

The calling identity and its limits.

Every Product in the organisation this key belongs to, newest first. Returns a summary per Product (id, name, region, environments and health), not the full graph; call product_get for that. A key confined to a single Product sees only that one.

Scopes

product:read

Returns

A JSON object.

A Product is the unit everything else hangs from: environments, services, databases, auth, storage, domains, secrets and context. Creating one provisions nothing billable on its own: it is the empty graph. Pass external_ref to make this idempotent against your own identifiers.

Scopes

product:write

Returns

What would happen, what it would cost, and what could not be undone.

The whole resource graph for one Product: environments, services, databases, domains, secrets (names only, never values), context linkage and current health. This is the single call to make before reasoning about a Product.

Scopes

product:read

Returns

The Product and its full resource graph.

Changes the name a Product is shown under: the dashboard, the sender name on its auth emails and the activity trail. Addresses do not change. Its helm7.app hostnames, image names and ids stay exactly as they were, so nothing already deployed or pointed at it moves. A Contextely product created by context_enable keeps the name it was given then.

Scopes

product:write

Returns

What would happen, what it would cost, and what could not be undone.

Destroys every environment, service, database, bucket and domain binding under the Product. Databases are backed up first and the backup is retained for 7 days, but the running resources are gone. Requires confirm: true; without it you get the plan and nothing happens.

Scopes

product:delete

Returns

What would happen, what it would cost, and what could not be undone.

Environments in a Product, each with a summary of the services, databases and domains bound to it. Every Product has production; preview and development exist only if created. Use this to find an environment name before calling anything scoped to one.

Scopes

product:read

Returns

A JSON object.

Adds preview or development alongside production. A new environment starts empty; it does not copy production data. Use database_branch for that, when you want a copy.

Scopes

product:write

Returns

What would happen, what it would cost, and what could not be undone.

Stops every service in a preview or development environment and removes its databases, buckets, domains and variables. Production cannot be deleted this way; delete the Product instead. Requires confirm: true.

Scopes

product:delete

Returns

What would happen, what it would cost, and what could not be undone.

Adds a web, worker or cron service. Helm7 detects the framework from the repo and picks a build; you only need to override when detection is wrong. A service has no execution time limit, so long jobs do not need splitting.

Scopes

product:write, deployment:write

Returns

What would happen, what it would cost, and what could not be undone.

Recent stdout and stderr for a service. Secrets are redacted on a best-effort basis before the logs leave the platform; treat redaction as a safety net, not a guarantee.

Scopes

deployment:read

Returns

A JSON object.

Every service in a Product with its kind, instance size, whether it sleeps, its status, the deployment it is running and the address it answers on. Filter by environment. Use this to find a service id before reading its logs or changing it.

Scopes

product:read

Returns

A JSON object.

Changes the instance size, the branch or directory it builds from, whether pushes that miss that directory skip the build, the image, the schedule of a cron service, or pauses it. Size and pause take effect at once on a running service; source changes take effect on the next deploy. Returns a costed plan, because a bigger instance costs more.

Scopes

product:write, deployment:write

Returns

What would happen, what it would cost, and what could not be undone.

Stops the service and removes it with its deployment history. Domains pointing at it are detached. Databases and variables in the environment are not touched. Requires confirm: true.

Scopes

product:delete

Returns

What would happen, what it would cost, and what could not be undone.

Builds the current commit and swaps traffic to it once health checks pass. The previous deployment is kept and can be restored with deployment_rollback. Returns immediately with a deployment id; poll deployment_get for progress. Through MCP a build from a repository is built on your own machine by default, so it never waits in Helm7's build queue: nothing builds until you run the `local_build.command` in the response (the CLI builds, uploads and starts it) in a shell with Docker and the repository. If you have no shell or Docker, call deploy again with `build: "remote"`, which replaces it and builds on Helm7 (use build_queue_get to see how long the queue is).

Scopes

deployment:write

Returns

What would happen, what it would cost, and what could not be undone.

Status, timing, commit, build logs and, when a deployment failed, the specific reason, extracted rather than left for you to find in the log tail.

Scopes

deployment:read

Returns

The deployment, its status and its failure reason where one exists.

Deployment history for a Product, newest first, with status, commit and timing for each. History is immutable and nothing is pruned, so this is the reliable way to find the last deployment that was healthy before rolling back to it.

Scopes

deployment:read

Returns

A JSON object.

Moves traffic back to an earlier deployment. The image already exists, so this is a traffic swap and takes seconds. It does not revert database migrations. If the newer deployment migrated the schema, roll that back yourself first.

Scopes

deployment:write

Returns

What would happen, what it would cost, and what could not be undone.

Your workspace's builds that are running or waiting for a build slot, in the order they will run, with each one's place in the whole queue and how many builds start before it. Builds from other workspaces are counted but never named. Higher plans start ahead of lower ones, by a head start that is reported as head_start_minutes. typical_build_seconds is the median of your recent builds, or null until you have some. A deploy that builds on your own machine never appears here.

Scopes

deployment:read

Returns

Your running and waiting builds with their positions, and the size of the queue.

Puts your own waiting builds in a new order. The ids you list run first, in that order; your other waiting builds follow in the order they already had. It only rearranges the places your workspace already holds in the queue, so it can never put a build ahead of another workspace's, and your earliest place stays your earliest place. A build that has started cannot be moved: it is reported as not waiting. Returns the queue as it stands afterwards.

Scopes

deployment:write

Returns

What would happen, what it would cost, and what could not be undone.

Adds one chunk of a `docker save` archive to a deployment that was started with a local build. Chunks go in order: `offset` must equal what has been received so far, which makes a retry after a dropped connection safe, and the response says how many bytes are held. Finish with deployment_image_finish. The CLI does this for you.

Scopes

deployment:write

Returns

How many bytes of the image are held.

Checks the uploaded archive against the size and sha256 you give, loads it onto the region and starts the deployment from it. It goes live the same way a remote build does: traffic moves once the new run is healthy. Poll deployment_get for progress.

Scopes

deployment:write

Returns

The deployment, now starting.

Creates a Postgres database, at the major version the region runs, with pgvector available, and sets DATABASE_URL on the environment. Connections are pooled; use the pooled URL for serverless-style workloads and the direct URL for migrations.

Scopes

database:write

Returns

What would happen, what it would cost, and what could not be undone.

Size, extensions, connection counts and backup state. Connection strings are returned only to a key carrying database:read, and the password is shown only on creation.

Scopes

database:read

Returns

The database and its current state.

Takes a backup now, on top of the daily ones paid plans get. Kept 7 days. Returns a backup id usable with database_restore.

Scopes

database:write

Returns

What would happen, what it would cost, and what could not be undone.

Restores from a backup id or to a timestamp. This REPLACES the current database contents: everything written after the restore point is lost. Requires confirm: true. Restore into a fresh database first if you are not certain.

Scopes

database:write

Returns

What would happen, what it would cost, and what could not be undone.

Runs one read-only SQL statement (SELECT, WITH, VALUES or TABLE) against a Product's database and returns the rows as JSON. It runs as the Product's own database role inside a READ ONLY transaction with a 15 second timeout, so it cannot change anything and cannot see another Product's data. At most `limit` rows come back (default 100, maximum 1000); `truncated` says whether there were more. Use it to inspect schema (information_schema.columns) and data before deciding on a change, then database_execute to change it. Reads are not audited.

Scopes

database:read

Returns

The rows, and whether the limit cut them short.

Runs a SQL script (INSERT, UPDATE, DELETE, DDL, several statements) against a Product's database as the Product's own database role, in one transaction: if any statement fails nothing is kept. `dry_run: true` really runs the script and then rolls it back, so you learn whether it would succeed and, through a final SELECT or a RETURNING clause, what it would produce, without changing anything. Applying requires `confirm: true` because a bad UPDATE cannot be undone: take a database_backup first when the change is large. Row counts are not reported; end with a RETURNING clause or a SELECT count(*) when you need one. Transaction control (BEGIN, COMMIT, ROLLBACK, SAVEPOINT) is refused because the script already is one transaction. The first 500 characters of the SQL are kept in the audit trail, so keep secrets out of it; use secret_set for those.

Scopes

database:write

Returns

What would happen, what it would cost, and what could not be undone.

Starts a GoTrue auth service (the engine behind Supabase Auth) against the Product database, on its own hostname, and sets AUTH_URL, AUTH_ANON_KEY, AUTH_SERVICE_ROLE_KEY, AUTH_JWT_SECRET and AUTH_SITE_URL on the environment. supabase-js and @supabase/ssr work against it unchanged: pass AUTH_URL (an origin, no path) and AUTH_ANON_KEY. Sign-in email goes out through Helm7, so nothing needs configuring for it. Calling it again on an environment whose auth is recorded but not running starts the missing container and keeps every key already in use; it never rotates a key. The record only reads available once the container passes its health check.

Scopes

product:write

Returns

What would happen, what it would cost, and what could not be undone.

The state of the auth service for one environment: whether its container is healthy right now, the URL apps use, its non-secret configuration, and how many users and identities it holds. The counts are how a migration proves every user arrived. No secret, key or password hash is ever returned; secret_list shows which variables exist.

Scopes

product:read

Returns

The auth service, its URL, configuration and user counts.

Changes how the auth service behaves: the site URL and the allow-list of redirect URLs, whether email needs confirming, whether new sign-ups are closed, whether anonymous sign-ins are allowed, which OAuth providers are on (Google and GitHub, with their client id and secret, stored as secrets and never returned), the minimum password length, how long access tokens last and how refresh tokens rotate. Only the fields you send change. The service restarts on the new settings with the old one serving until the new one is healthy. Signed-in users are not signed out. A field this operation does not have is refused by name, not ignored.

Scopes

product:write

Returns

What would happen, what it would cost, and what could not be undone.

Upserts a batch of users, with their provider identities, into the auth schema of the Product database, keeping each id, email, password hash, confirmation time, timestamps and metadata, so nobody has to reset a password. Hashes must be bcrypt ($2a$, $2b$, $2y$) or argon2 ($argon2i$, $argon2id$); scrypt and anything else is refused, naming the row. Idempotent on id: running a batch twice changes nothing the second time. Up to 200 users per call. Hashes are never logged and never returned; the response carries counts only. Compare them with auth_get to verify a migration.

Scopes

database:write

Returns

What would happen, what it would cost, and what could not be undone.

S3-compatible object storage with no egress charge. The API is Supabase Storage compatible, so supabase-js storage calls work unchanged.

Scopes

product:write

Returns

What would happen, what it would cost, and what could not be undone.

Buckets in a Product, each with its environment, whether it is public, its size and the S3-compatible name to address it by. Objects themselves are listed through the S3 API, not here.

Scopes

product:read

Returns

A JSON object.

Removes the bucket and everything stored in it. There is no recycle bin. Requires confirm: true.

Scopes

product:delete

Returns

What would happen, what it would cost, and what could not be undone.

Binds a domain to a web service and issues a certificate. Returns the DNS record to create; the certificate is issued once that record resolves, usually within a minute. Until then the domain is listed as pending, which is not an error. A name under a domain (app.example.com, www.example.com) takes a CNAME. A bare domain (example.com) takes an A record to a fixed address and, by default, redirects to www.example.com, which is attached with it if it is not already; this works at any DNS provider. Pass serve: true to answer on the bare domain itself instead of redirecting, for a site whose address people know without the www, or a webhook or API that calls it (a redirect drops the body of a POST for clients that do not follow it).

Scopes

domain:write

Returns

What would happen, what it would cost, and what could not be undone.

Domains bound to a Product, with certificate status and the DNS record each one expects.

Scopes

domain:read

Returns

A JSON object.

Unbinds the domain and revokes its certificate. Traffic to it stops immediately. Requires confirm: true.

Scopes

domain:write

Returns

What would happen, what it would cost, and what could not be undone.

Sets or replaces a variable for an environment. Values are encrypted at rest and are never returned by any read endpoint, including this one. Only names and a fingerprint come back. Services pick up the change on their next deployment.

Scopes

secret:write

Returns

What would happen, what it would cost, and what could not be undone.

Names, environments and fingerprints. Values are never returned. There is no endpoint that returns them, by design, so a leaked read key cannot exfiltrate credentials.

Scopes

secret:read

Returns

A JSON object.

Removes a variable from one environment. Running services keep the value until their next deploy. The value cannot be recovered, which is why this requires confirm: true.

Scopes

secret:write

Returns

What would happen, what it would cost, and what could not be undone.

Makes a sign-in a tester can use to drive the product's real interface, kept per environment. mode `provision` creates the user in the environment's managed auth: Helm7 generates a strong password, stores only a hash in auth and an encrypted copy of its own, confirms the address, and tags the user (app_metadata.is_test = true, email <label>+helm7test@<domain>) so analytics and revenue views can leave it out. Needs managed auth enabled, so run auth_enable first. mode `external` does the same in the Product's own auth service instead, with auth_provider (today: supabase): Helm7 reads the project URL and admin key from the environment's stored variables (NEXT_PUBLIC_SUPABASE_URL or SUPABASE_URL, and SUPABASE_SERVICE_ROLE_KEY), uses them for that one call and never returns them, so a Product whose auth lives elsewhere needs no key handed to the caller. The user is confirmed and tagged app_metadata.is_test; rotate and delete only ever touch a tagged user. mode `register` records an account somebody created elsewhere (a product hosted outside Helm7): send its email and password, and optionally a TOTP seed. Nothing here is ever returned: the password and seed are write-only, and list and get show a fingerprint and whether a seed exists. The one way to read them is test_account_checkout. Pass expires_in (for example 24h or 7d) or expires_at to make the account temporary: once it passes, the account is disabled, its stored secrets are wiped and, for provision, its auth user is removed, within about five minutes. Leave both out for a long-lived account. Test accounts must never pay for anything real; a flow that reaches a live paywall should stop there.

Scopes

test_account:write

Returns

What would happen, what it would cost, and what could not be undone.

The test accounts of an environment: label, role, email, mode, a fingerprint of the password, whether a TOTP seed is stored, status (active, expired), when it expires, when it was last checked out and by which run, and when it was last rotated. Never a password, a seed or a code.

Scopes

test_account:read

Returns

A JSON object.

One test account with the same fields as the list: label, role, email, mode, fingerprint, whether it has a TOTP seed, status, expiry, last use and last rotation. Never a password, a seed or a code. Use test_account_checkout to sign in as it.

Scopes

test_account:read

Returns

A test account, without its secrets.

Replaces the password. provision: Helm7 generates a new one and changes it in managed auth too, which also signs out every session the account has. register: send the new password you have set in the product, because Helm7 cannot reach it. The stored TOTP seed is left alone unless totp_secret is sent. Nothing secret is returned; the new fingerprint is. An expired account cannot be rotated.

Scopes

test_account:write

Returns

What would happen, what it would cost, and what could not be undone.

Removes the record and its stored secrets and, for a provision account, deletes the user from managed auth along with its sessions. Only a user tagged is_test can be removed this way, so a real customer is never at risk from a wrong id. Requires confirm: true.

Scopes

test_account:write

Returns

What would happen, what it would cost, and what could not be undone.

The one operation that returns a test account's secrets: email, password, the current TOTP code if it has a seed and, for a provision account, a real session so the caller need not sign in at all. Meant for whatever signs in to the product, an agent included. Type the values into the sign-in and do not repeat them in your reply or write them to a file. Prefer a short-lived account (expires_in on create) and a short lease. run_ref is required and is written to the activity log with who asked, so every use is traceable to a run. The result is never kept for replay. The checkout is a lease of ttl_seconds (default 900, from 60 to 3600): when it ends, the sessions Helm7 minted for the account are revoked, so a credential that leaks from a finished run stops working quickly. Refused for an expired account.

Scopes

test_account:use

Returns

Email, password, totp_code and session for the account. This response is a credential: do not log it.

The current six-digit code for a test account that has a TOTP seed, with the seconds it stays valid. The seed never leaves Helm7, so a caller that needs a fresh code mid-flow asks again rather than holding the seed. Every call stamps the account’s last-used time, and run_ref if given, but is not written to the activity log on its own, because a flow may ask every few seconds; the checkout it follows is. Returns a code and nothing else.

Scopes

test_account:use

Returns

A one-time code. Do not log it.

Creates a Contextely product scoped to this Helm7 Product and sets its credentials on the environment, so agents operating the application can read and write its context. Memory and sources are private to this Product unless you say otherwise.

Scopes

context:write

Returns

What would happen, what it would cost, and what could not be undone.

This month's spend, measured hourly from what actually ran, broken down by Product and resource; the projection to month end at what is running now; what the workspace as it stands would cost over a whole month; and the budget remaining if one is set. Read this before creating anything expensive.

Scopes

billing:read

Returns

Usage, spend to date and month-end projection.

What a given set of resources would cost per month, without creating anything. Use this to choose between shapes before you build one. Free and side-effect-free.

Scopes

billing:read

Returns

The estimated monthly cost, itemised, with the largest driver named.

A hosted Stripe Checkout URL for upgrading the organisation to a paid plan. For an organisation that has never paid, nothing changes yet: the plan updates when Stripe confirms the subscription. For one that already pays, the existing subscription changes plan in place straight away, with no Checkout page.

Scopes

billing:manage

Returns

A Checkout URL to redirect the customer to.

A Stripe-hosted page where a person changes plan, updates the card, downloads invoices or cancels. Only for an organisation that has paid before; one that has not starts with billing_checkout_create.

Scopes

billing:manage

Returns

A portal URL to redirect the person to.

Creates a key for one agent, with its own scopes, an optional spend cap and an optional expiry. The key can never exceed the scopes of the member minting it, and a key holding may_administer cannot mint another key holding may_administer, which is what makes revoking one mean something. The secret is shown once and never again.

Scopes

agent:manage

Returns

What would happen, what it would cost, and what could not be undone.

Stops the key immediately. In-flight requests using it fail. Revocation cannot be undone; mint a new key instead.

Scopes

agent:manage

Returns

What would happen, what it would cost, and what could not be undone.

Every key in the organisation: its name, the first characters of the secret, its scopes and capabilities, the Product it is confined to, its spend against its cap, its expiry and when it was last used. Never the secret. Revoked keys are included, marked as revoked, because the audit trail still names them.

Scopes

agent:manage

Returns

A JSON object.

Creates a temporary organisation and a scoped key with no email, no card and no human step, so an agent can try Helm7 end to end. One Product, a small quota, and it expires. This is for experimentation, not for running anything real. Call cloud_claim to keep what you built.

Scopes

none: this endpoint is unauthenticated

Returns

The ephemeral organisation, its key, its quota and its expiry.

Returns a single-use link a person opens to attach this ephemeral workspace to their account. The workspace keeps running while they do. Claiming keeps it; choosing Builder or Pro is what lifts the 72-hour expiry and the trial quota.

Scopes

none: this endpoint is unauthenticated

Returns

A claim URL and how long it stays valid.

The workspace this key belongs to: its name, plan, spend cap, whether it is a trial and when it expires, and what it is committed to spend this month across every Product. Call this before planning anything large.

Scopes

billing:read

Returns

The organisation, its plan, cap and committed monthly cost.

Changes the workspace name, its monthly spend cap, where deploys build by default, or whether services keep their helm7.app address. The spend cap is checked against every cost-impacting change, whoever or whatever makes it; set budget_usd to null to remove it. default_build_mode is where a deploy builds when the caller does not say: local on the machine running the CLI, remote in the platform's build queue. A deploy from somewhere that cannot build (the dashboard, a push to GitHub, the hosted MCP server) always builds remotely. keep_app_domain decides whether a service keeps answering on its helm7.app address once a custom domain is serving it; off by default, so the custom domain replaces it. Turn it on to keep helm7.app as a staging address.

Scopes

billing:manage

Returns

What would happen, what it would cost, and what could not be undone.

The audit trail: every change, whether it was applied, refused or failed, who made it (a person or a named key) and the plan it carried. Refusals are included, so an agent that was stopped is on the record. Newest first.

Scopes

product:read

Returns

A JSON object.

People with access to the workspace, with their role, and invitations that have not been accepted yet. There is no charge per person, so this is about who can do what, not what it costs.

Scopes

product:read

Returns

A JSON object.

Returns a link that adds whoever opens it and signs in to the workspace, with the role given. The link is shown once, works once and expires after 7 days. Nothing is emailed; send it however you like.

Scopes

member:manage

Returns

What would happen, what it would cost, and what could not be undone.

Removes a person, revoking every key they minted, or cancels an invitation that has not been used. The last owner cannot be removed. Requires confirm: true.

Scopes

member:manage

Returns

What would happen, what it would cost, and what could not be undone.

Repositories the workspace has given the Helm7 GitHub App access to, most recently pushed first, with their default branch and whether they are private. When the app is not installed yet, says so and returns the link a person follows to install it.

Scopes

product:read

Returns

Installations, their repositories, and an install link.

Connects a repository the GitHub App can see to a Product. Every push to the production branch then builds and deploys, recorded as triggered by the push. Private repositories are cloned with a short-lived token that is never stored.

Scopes

product:write

Returns

What would happen, what it would cost, and what could not be undone.