Launch a Stack

Launching a stack is a two-step flow: preview the cost first, then send the launch request with the cost you accepted. This ensures you always see an up-to-date estimate before any billable resource is created.

Prerequisites

• An API token. See Authentication.
• If the stack you want to launch includes inference (currently rag-chatbot), your organization must have an enabled inference provider configured. The launch fails at the preview step if no provider is available.

Step 1: Choose a template

List the first-party catalog to see available templates and their current cost breakdowns:

curl https://api.foundrydb.com/stacks/templates \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN"

Each entry includes name, display_name, version, and a cost_preview computed fresh on every call.

To browse community templates published to the marketplace:

curl https://api.foundrydb.com/stacks/templates/marketplace \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN"

Step 2: Preview the cost

Before launching, request a cost preview. For a first-party template:

curl -X POST https://api.foundrydb.com/stacks/preview \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_name": "rag-chatbot"}'

For a marketplace template, pass template_id instead:

curl -X POST https://api.foundrydb.com/stacks/preview \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "'$TEMPLATE_ID'"}'

The response looks like this:

{
  "template_name": "rag-chatbot",
  "currency": "USD",
  "monthly_total": 87.00,
  "line_items": [
    {
      "symbolic_name": "db",
      "kind": "database",
      "description": "PostgreSQL tier-2 (2 vCPU, 4 GB) + 50 GB maxiops storage",
      "monthly_cost": 42.00,
      "is_ceiling": false
    },
    {
      "symbolic_name": "inference",
      "kind": "inference",
      "description": "EU-routed inference key — monthly budget ceiling",
      "monthly_cost": 20.00,
      "is_ceiling": true
    }
  ],
  "warnings": [
    "The inference line item is a monthly budget ceiling, not a guaranteed charge."
  ]
}

monthly_total is the number you pass to the launch request. Line items marked is_ceiling: true are maximum charges (such as an inference budget), not fixed recurring costs.

Step 3: Launch

Pass the monthly_total from the preview as accepted_monthly_cost:

curl -X POST https://api.foundrydb.com/stacks \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-rag-chatbot",
    "template_name": "rag-chatbot",
    "accepted_monthly_cost": 87.00
  }'

To launch a marketplace template, replace template_name with template_id:

curl -X POST https://api.foundrydb.com/stacks \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-stack",
    "template_id": "'$TEMPLATE_ID'",
    "accepted_monthly_cost": 42.00
  }'

The response is 201 Created with the stack in Pending status.

Overriding resource defaults

You can adjust individual resource specs beyond the template defaults using overrides, keyed by the resource's symbolic name:

curl -X POST https://api.foundrydb.com/stacks \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-rag-large",
    "template_name": "rag-chatbot",
    "accepted_monthly_cost": 130.00,
    "overrides": {
      "db": {"plan_name": "tier-4"}
    }
  }'

Unknown override keys are rejected. Re-preview after adding overrides, since they change the cost.

Cost gate behaviour

Scenario	HTTP status
accepted_monthly_cost omitted	400 Bad Request
No enabled inference provider (inference stack)	400 Bad Request
Accepted cost drifted from current estimate by more than $0.01	409 Conflict — re-preview required

Step 4: Poll for status

The stack provisions asynchronously. Poll GET /stacks/{stack-id} until status reaches Running:

curl https://api.foundrydb.com/stacks/$STACK_ID \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN"

The response includes a resources array showing each child resource's own status and a service_id or ref_id pointer once it is provisioned. Once the stack is Running, the endpoint_url field carries the live application URL.

Typical progression: Pending → Provisioning → Wiring → Running. Provisioning time varies by template, but most stacks complete within 5 minutes.

What gets created

Every child resource becomes an ordinary service in your account. For the rag-chatbot template, you get:

• A PostgreSQL service with the pgvector extension, visible under Databases.
• A Files bucket, visible under Files.
• An inference key scoped to the stack, visible under AI.
• An Open WebUI app service, visible under Apps.

Each resource is owned by your account and billed through your normal plan. Deleting the stack removes all of them atomically.

Teardown

curl -X DELETE https://api.foundrydb.com/stacks/$STACK_ID \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN"

Returns 202 Accepted. The reconciler deletes every child resource in reverse dependency order. No child resource is left orphaned. Teardown is irreversible.

Retrying a failed stack

If the stack reaches Failed (after the engine rolls back all child resources), you can retry:

curl -X POST https://api.foundrydb.com/stacks/$STACK_ID/retry \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN"

Retry resets the stack to Pending and provisions fresh from the start. Only a stack in Failed status can be retried; any other status returns 409 Conflict.