---
title: "Create a card-gated trial runtime"
method: POST
path: "/v1/onboarding/guided/trial/runtime"
tags: ["Organization"]
---

# Create a card-gated trial runtime

`POST /v1/onboarding/guided/trial/runtime`

## Request

- Base URL: `https://api.1claw.co`
- URL: `https://api.1claw.co/v1/onboarding/guided/trial/runtime`
- Auth: HTTP bearer

Verifies the given SetupIntent succeeded, then delegates to the same
runtime-creation logic `POST /v1/runtimes` uses. Only reachable once
the guided onboarding wizard has a confirmed SetupIntent for the org.

## Request body

- CreateTrialRuntimeRequest
  - `setup_intent_id` string, required
  - `agent_id` string, uuid, required
  - `template` string, required
  - `preset` string: Defaults to CreateRuntimeRequest's own default ("small") when omitted.
  - `name` string, required
  - `always_on` boolean: Keeps the runtime running indefinitely instead of auto-stopping after the default idle window (maps to `idle_timeout_secs: 0`).
  - `env_public` object: Non-secret runtime config — in practice just `LLM_PROVIDER`/`LLM_MODEL` from the guided flow's model-choice step. Rejected if any key looks secret-shaped (same `validate_env_public` the canonical runtime API uses).

## Response `201`

Created runtime

- RuntimeResponse
  - `previous_image_digest` string, nullable
  - `image_digest` string, nullable: Resolved image (digest form when the provider reports one); runtime-minted agent tokens carry it as `runtime_image`, which access policies can require via `conditions.runtime_image_in`.
  - `schedule` object, nullable
  - `next_scheduled_start_at` string, date-time, nullable
  - `scheduled_stop_at` string, date-time, nullable
  - `id` string, uuid, required
  - `name` string, required
  - `agent_id` string, uuid, required
  - `template` string, nullable
  - `preset` string, nullable
  - `provider` string, nullable
  - `status` 'creating' | 'running' | 'stopping' | 'stopped' | 'failed' | 'deleting', required
  - `image` string, nullable
  - `environment` string, nullable: Vault environment for env var resolution
  - `env_public` object, nullable
  - `idle_timeout_secs` integer, nullable
  - `expose_http` boolean, nullable
  - `slug` string, nullable
  - `public_url` string, nullable
  - `http_port` integer, nullable
  - `inbound_auth` 'api_key' | 'jwt' | 'public', nullable
  - `shell_access_enabled` boolean
  - `shell_auth_policy` string
  - `shell_max_session_minutes` integer
  - `monthly_hours_used` number, nullable
  - `has_paid_addon` boolean: Whether this runtime has a paid Stripe add-on (unlimited hours).
  - `billing_kind` 'pool' | 'included' | 'addon': `pool` — counts against the plan's monthly runtime hours. `included` — the plan's free runtime (every plan from Pro up includes one small or medium runtime, no hour cap, no charge). `addon` — paid Stripe subscription item (no hour cap).
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

---

[API](https://skmtc.dev/1claw/apis/1claw-api.md) · [All operations](https://skmtc.dev/1claw/apis/1claw-api/llms.txt) · [OpenAPI document](https://skmtc.dev/1claw/apis/1claw-api/revisions/ae109b496830?raw)