# Helm7

Deploy and operate a whole application (compute, Postgres, auth, storage, domains and jobs) through one API, one CLI and one MCP server.

Base URL: https://www.helm7.com
OpenAPI: https://www.helm7.com/v1/openapi.json
Auth: `Authorization: Bearer hlm_sk_...`
MCP: https://www.helm7.com/mcp. A client that supports OAuth (Claude Code: `claude mcp add --transport http helm7 https://www.helm7.com/mcp`, then Authenticate) signs in through the browser and is issued a key; any other client sends an API key as above.

## Read this before you call anything

1. **Call `whoami` first.** A key resolves to a member and cannot exceed what that member can do. It may also carry a spend cap and an expiry. Knowing your ceiling costs one call and saves guessing.

2. **Plan before you act.** Every operation that changes infrastructure takes `dry_run: true` and returns what would change, what it would cost per month, and what could not be undone. Dry runs are free and have no side effects.

3. **Destructive operations refuse without `confirm: true`.** A refusal returns the same plan a dry run would, so a caller that always plans first never hits a surprise.

4. **Use `idempotency_key` on anything that creates or spends.** Replaying a key returns the original result rather than acting twice.

5. **Secret values are never readable.** No endpoint returns them. `secret_list` gives names and fingerprints only. The one deliberate exception is `test_account_checkout` (and `test_account_totp`), which hand a test user's sign-in to a caller holding the separate `test_account:use` scope and are recorded with the run that asked. Both are offered over MCP: prefer a temporary account and do not repeat the values in a reply.

6. **Cost is first-class.** `cost_estimate` prices a shape without building it. `usage_get` shows spend to date and the month-end projection.

## Resource graph

Everything hangs off a Product:

    Organization → Product → Environment → Service | Database | Auth | Storage | Domain | Secret | Context

A Product is the unit, not a "project" or a bare container. One Product is one application, with everything it needs to run.

## Typical first session

    cloud_init                 → an ephemeral workspace, no account needed
    product_create             → dry_run first, then apply
    database_create
    auth_enable
    deploy
    domain_attach
    cloud_claim                → keep it

## Errors

Every failure returns `{ error: { code, message, remedy, request_id } }`. Codes are stable; branch on `code`, never on `message`. `remedy` tells you what to do and is present whenever a remedy exists.

Notable codes: `insufficient_scope`, `confirmation_required`, `budget_exceeded`, `quota_exceeded`, `plan_limit`, `not_found`, `conflict`, `rate_limited`.

## Operations

### Identity

- `whoami`: GET /v1/whoami
  Identify the calling credential.

### Products

- `product_list`: GET /v1/products
  List Products.
- `product_create`: POST /v1/products
  Create a Product.
- `product_get`: GET /v1/products/:productId
  Inspect a Product.
- `product_update`: PATCH /v1/products/:productId
  Rename a Product.
- `product_delete`: DELETE /v1/products/:productId  [DESTRUCTIVE]
  Delete a Product and everything in it.

### Environments

- `environment_list`: GET /v1/products/:productId/environments
  List environments.
- `environment_create`: POST /v1/products/:productId/environments  [costs money]
  Create an environment.
- `environment_delete`: DELETE /v1/products/:productId/environments/:environment  [DESTRUCTIVE]
  Delete an environment and everything in it.

### Services

- `service_create`: POST /v1/products/:productId/services  [costs money, needs may_deploy]
  Create a service.
- `service_logs`: GET /v1/products/:productId/services/:serviceId/logs
  Read runtime logs.
- `service_list`: GET /v1/products/:productId/services
  List services.
- `service_update`: PATCH /v1/products/:productId/services/:serviceId  [costs money]
  Change how a service runs.
- `service_delete`: DELETE /v1/products/:productId/services/:serviceId  [DESTRUCTIVE]
  Delete a service.

### Deployments

- `deploy`: POST /v1/products/:productId/deployments  [costs money, needs may_deploy]
  Build and deploy.
- `deployment_get`: GET /v1/products/:productId/deployments/:deploymentId
  Inspect a deployment.
- `deployment_list`: GET /v1/products/:productId/deployments
  List deployments.
- `deployment_rollback`: POST /v1/products/:productId/deployments/:deploymentId/rollback  [needs may_deploy]
  Roll back to a previous deployment.
- `build_queue_get`: GET /v1/build-queue
  Where your builds are in the queue.
- `build_queue_reorder`: POST /v1/build-queue/order  [needs may_deploy]
  Reorder your waiting builds.
- `deployment_image_upload`: POST /v1/products/:productId/deployments/:deploymentId/image  [needs may_deploy]
  Upload a locally built image.
- `deployment_image_finish`: POST /v1/products/:productId/deployments/:deploymentId/image/finish  [needs may_deploy]
  Deploy a locally built image.

### Databases

- `database_create`: POST /v1/products/:productId/databases  [costs money]
  Provision Postgres.
- `database_get`: GET /v1/products/:productId/databases/:databaseId
  Inspect a database.
- `database_backup`: POST /v1/products/:productId/databases/:databaseId/backups
  Take a backup now.
- `database_restore`: POST /v1/products/:productId/databases/:databaseId/restore  [DESTRUCTIVE]
  Restore to a point in time.
- `database_query`: POST /v1/products/:productId/databases/:databaseId/query
  Read rows with SQL.
- `database_execute`: POST /v1/products/:productId/databases/:databaseId/execute  [DESTRUCTIVE]
  Change data or schema with SQL.

### Auth

- `auth_enable`: POST /v1/products/:productId/auth  [costs money]
  Enable managed auth.
- `auth_get`: GET /v1/products/:productId/auth
  Inspect managed auth.
- `auth_update`: PATCH /v1/products/:productId/auth
  Configure managed auth.
- `auth_users_import`: POST /v1/products/:productId/auth/users/import
  Import users into managed auth.

### Storage

- `storage_create_bucket`: POST /v1/products/:productId/storage/buckets  [costs money]
  Create a storage bucket.
- `bucket_list`: GET /v1/products/:productId/storage/buckets
  List storage buckets.
- `bucket_delete`: DELETE /v1/products/:productId/storage/buckets/:bucketId  [DESTRUCTIVE]
  Delete a storage bucket and every object in it.

### Domains

- `domain_attach`: POST /v1/products/:productId/domains  [costs money]
  Attach a custom domain.
- `domain_list`: GET /v1/products/:productId/domains
  List domains.
- `domain_remove`: DELETE /v1/products/:productId/domains/:domainId  [DESTRUCTIVE]
  Remove a domain.

### Secrets

- `secret_set`: POST /v1/products/:productId/secrets
  Set an environment variable.
- `secret_list`: GET /v1/products/:productId/secrets
  List secret names.
- `secret_delete`: DELETE /v1/products/:productId/secrets/:key  [DESTRUCTIVE]
  Remove an environment variable.

### Test accounts

- `test_account_create`: POST /v1/products/:productId/test-accounts
  Create a test account.
- `test_account_list`: GET /v1/products/:productId/test-accounts
  List test accounts.
- `test_account_get`: GET /v1/products/:productId/test-accounts/:accountId
  Inspect a test account.
- `test_account_rotate`: POST /v1/products/:productId/test-accounts/:accountId/rotate
  Rotate a test account password.
- `test_account_delete`: DELETE /v1/products/:productId/test-accounts/:accountId  [DESTRUCTIVE]
  Delete a test account.
- `test_account_checkout`: POST /v1/products/:productId/test-accounts/:accountId/checkout
  Check out a test account to sign in with.
- `test_account_totp`: POST /v1/products/:productId/test-accounts/:accountId/totp
  Get the current two-factor code.

### Context

- `context_enable`: POST /v1/products/:productId/context  [costs money]
  Give the Product memory.

### Billing and cost

- `usage_get`: GET /v1/usage
  Current usage and spend.
- `cost_estimate`: POST /v1/cost/estimate
  Price a hypothetical shape.
- `billing_checkout_create`: POST /v1/billing/checkout
  Start a Stripe Checkout session.
- `billing_portal_create`: POST /v1/billing/portal
  Open the billing portal.

### Agents

- `agent_key_create`: POST /v1/agent-keys  [needs may_administer]
  Mint a scoped agent credential.
- `agent_key_revoke`: DELETE /v1/agent-keys/:keyId  [DESTRUCTIVE, needs may_administer]
  Revoke an agent credential.
- `agent_key_list`: GET /v1/agent-keys
  List keys.
- `cloud_init`: POST /v1/cloud/init
  Start an ephemeral workspace with no account.
- `cloud_claim`: POST /v1/cloud/claim
  Keep an ephemeral workspace.

### GitHub

- `github_repo_list`: GET /v1/github/repositories
  List repositories Helm7 can deploy from GitHub.
- `product_connect_repo`: POST /v1/products/:productId/github
  Deploy a Product from a GitHub repository on every push.

### Workspace

- `organization_get`: GET /v1/organization
  Read the workspace.
- `organization_update`: PATCH /v1/organization  [needs may_administer]
  Change workspace settings.
- `activity_list`: GET /v1/activity
  What has been done, and by whom.
- `member_list`: GET /v1/members
  List the people in the workspace.
- `invite_create`: POST /v1/invites  [needs may_administer]
  Invite someone by link.
- `member_remove`: DELETE /v1/members/:memberId  [DESTRUCTIVE, needs may_administer]
  Remove someone from the workspace, or cancel an invitation.