Stacks Overview

A stack launches a complete, production-ready application with one button. Instead of provisioning a database, a files bucket, an inference resource, and an app separately and then wiring them together by hand, you pick a stack from the catalog, accept the cost, and click launch. The platform creates every piece, connects them, and hands you a live endpoint.

What a Stack Is

A stack composes existing FoundryDB primitives into one application. A single launch can include:

A managed database (for example, PostgreSQL with the pgvector extension).
A Files bucket for object storage.
An EU-routed inference resource that uses your own provider.
A hosted application that ties the pieces together.

The stack engine does not introduce a new provisioning path. It orchestrates the same brokered service APIs you would call yourself, in the right order, and injects the credentials and configuration each resource needs to reach the others. Everything is wired, credentialed, metered, and EU-resident from the moment it reaches the Running state.

Cost Preview Is a Hard Gate

Every launch is preceded by a cost preview. You cannot launch a stack without first accepting the per-month estimate it returns.

The accepted figure is sent back with the launch request. If the estimate has changed since you previewed it, the launch is rejected and you are asked to re-preview. This keeps the price you agreed to and the price you are charged in lockstep.

See The API for the exact request and response fields.

Atomic Rollback

A stack launch is all-or-nothing. If any child resource fails to provision, or you abort a launch in flight, the engine tears down every resource it had already created for that stack. A failed launch leaves no orphaned database, bucket, inference key, or app behind.

The lifecycle reflects this directly. A stack that hits a terminal child failure moves through RollingBack and lands in Failed only after every child has been removed.

No Platform-Default LLM

The inference resource in a stack uses your organization's own provider. There is no shared, platform-default model.

You configure the provider on the AI settings page before launching. If your organization has no inference provider configured, the launch fails loudly at the preview or launch gate rather than silently falling back to a default. This keeps your inference traffic on the provider and the EU routing you chose.

EU Residency

Stacks are composed entirely from EU-resident primitives. The database, files, app, and inference routing all stay within the platform's European footprint, so a stack inherits the same data-residency posture as the individual services it is built from.

Ownership

When you launch a stack, you own the resources it created. They are ordinary services in your account that you can inspect, scale, and manage individually.

A stack is launched from a catalog template at a specific version, and the descriptor is snapshotted onto your launch. If the catalog template is later bumped to a new version, your existing stacks are not auto-migrated. Your launched stack continues to run exactly as it was launched.

The Catalog

Five stacks are available today:

Stack	Template name	Composition
Launch a RAG chatbot	`rag-chatbot`	PostgreSQL with pgvector, Files, EU-routed inference, and Open WebUI.
Launch a CMS	`cms`	PostgreSQL and Directus.
Launch a BI workspace	`bi-workspace`	PostgreSQL and Metabase.
Launch a no-code database	`nocode-db`	PostgreSQL and NocoDB.
Launch a GraphQL API	`graphql-api`	PostgreSQL and Hasura.

The RAG chatbot stack is the only one that includes a Files bucket and an inference resource, because it pairs a vector store and EU-routed inference with the Open WebUI chat application. The other four pair a PostgreSQL database with a hosted application.

Lifecycle

A stack moves through a small set of states, driven by the platform. There is nothing to run by hand.

Pending -> Provisioning -> Wiring -> Running

RollingBack -> Failed        (on any terminal child failure or abort)
Deleting -> Deleted          (on teardown)

State	Meaning
`Pending`	The launch has been accepted and is queued.
`Provisioning`	One or more child resources are being created.
`Wiring`	Every child is running and cross-resource credentials and configuration are being injected.
`Running`	All resources are provisioned, wired, and the endpoint is live.
`RollingBack`	A terminal failure or abort triggered teardown of every created child.
`Failed`	Terminal state after rollback completes. No orphaned resources remain.
`Deleting`	A teardown of a running stack is in progress.
`Deleted`	Terminal state after a clean teardown.

The API

The Stacks API is available at https://api.foundrydb.com. All requests use Bearer authentication. See Authentication for how to obtain a token.

List the catalog

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

Preview the cost

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

The response includes a fixed_monthly_total. Use that value as the accepted cost when launching.

Launch a stack

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

accepted_monthly_cost is required and must match the figure from the preview:

Omit it and the request is rejected with 400 Bad Request.
Send a value that no longer matches the freshly computed estimate and the request is rejected with 409 Conflict, prompting you to re-preview.

List your stacks

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

Get a stack

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

The response carries the stack's status, its resources (each child with its own status), and the endpoint_url you connect to once the stack is Running.

Delete a stack

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

Deletion is an atomic teardown: every child resource of the stack is removed.

Retry a failed stack

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

A stack can only be retried once it has rolled back to Failed. The retry provisions the stack fresh from the start.

The Marketplace

Beyond the five first-party stacks, any organization can author its own stack template and share it with the rest of the platform through the marketplace.

Authoring a template

A template is a JSON or YAML descriptor that names the resources a stack composes, their kinds (database, files, inference, app), and the dependency ordering between them. You create one with a single API call:

curl -X POST https://api.foundrydb.com/stacks/templates \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-rag-pipeline",
    "display_name": "My RAG Pipeline",
    "description": "A custom retrieval-augmented pipeline.",
    "visibility": "private",
    "descriptor": {
      "apiVersion": "stacks.foundrydb.com/v1",
      "resources": [
        {"name": "db", "kind": "database", "spec": {"database_type": "postgresql", "version": "17", "plan_name": "tier-2", "storage_size_gb": 50, "storage_tier": "maxiops", "extensions": ["pgvector"]}},
        {"name": "app", "kind": "app", "spec": {"attachment_kind": "open-webui", "attached_to": "$db"}}
      ],
      "dependencies": {"app": ["db"]}
    }
  }'

The template starts in draft status with private visibility. You can update it with PATCH /stacks/templates/{id} while it is in a draft, rejected, or unpublished state. A published template is immutable; create a new version to change it.

Visibility and publication

Three visibility levels control who can discover and launch your template:

Visibility	Who can launch	Publication flow
`private`	Only members of your organization	Cannot be published
`org_shared`	All members of your organization	Published immediately on request
`public`	Any organization on the platform	Requires platform admin approval

To share a template within your organization, set visibility to org_shared and call:

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

The template is published immediately. To withdraw it, call POST /stacks/templates/$TEMPLATE_ID/unpublish.

To share a template with the entire platform, set visibility to public and publish it. The template enters a moderation queue (submitted status) and becomes publicly launchable only once a platform admin approves it. You can track the status with GET /stacks/templates/$TEMPLATE_ID.

Launching a marketplace template

Any template visible to your organization (your own org_shared templates, or a publicly published template from another organization) can be launched by passing its template_id instead of template_name.

The cost preview and launch gates work exactly the same way as for first-party templates: preview first, then pass the accepted cost:

# Preview the cost of a marketplace template
curl -X POST https://api.foundrydb.com/stacks/preview \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id":"'$TEMPLATE_ID'"}'

# Launch from the marketplace template
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 launched stack records source_template_id and source_publisher_org_id as provenance fields so you can trace which marketplace template it came from.

Listing marketplace templates

To browse templates published by other organizations:

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

To see your own organization's templates regardless of status:

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

Upgrading a stack

When the template a stack was launched from has been updated to a new version, you can adopt those changes in place without tearing the stack down, provided the changes are safe to apply non-destructively.

What can be upgraded in place

The upgrade engine classifies each resource's delta as one of three types:

Classification	Meaning
`unchanged`	No diff. The resource is not touched.
`in_place`	A safe, non-destructive change: app image redeploy, compute plan resize, inference key remint.
`blocked`	A change that requires recreating a stateful resource, changing a database engine or version, adding or removing a resource, or changing a container port. A fresh stack is required.

If any resource is blocked, the entire upgrade is blocked and cannot proceed in place.

Preview before applying

Always preview before upgrading. The preview returns the classified plan and the new monthly cost without changing any state:

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

The response includes from_version, to_version, changes (the per-resource plan), new_monthly_cost, cost_delta, and blocked with blocked_reasons when applicable.

Applying an upgrade

Once you have reviewed the plan and accepted the new cost:

curl -X POST https://api.foundrydb.com/stacks/$STACK_ID/upgrade \
  -H "Authorization: Bearer $FOUNDRYDB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accepted_monthly_cost": 95.00}'

Response semantics match the launch endpoint:

202 Accepted with a StackMigration record: the upgrade is in progress. The reconciler applies each change and updates the migration status to Completed.
200 OK with status: up_to_date: no changes to apply. The stack is already on the latest template version.
409 Conflict: an upgrade is already in progress, or the accepted cost drifted since preview (re-preview required).
422 Unprocessable Entity: the plan is blocked. Launch a fresh stack to adopt those changes.

A failed upgrade rolls back only the in-flight change and returns the stack to Running. It never tears the entire stack down.

Next Steps

Configure your inference provider on the AI settings page before launching a stack that uses inference.
Read the Authentication guide to set up an API token.
Explore the individual primitives a stack is built from in the Databases and Security sections.

What a Stack Is​

Cost Preview Is a Hard Gate​

Atomic Rollback​

No Platform-Default LLM​

EU Residency​

Ownership​

The Catalog​

Lifecycle​

The API​

List the catalog​

Preview the cost​

Launch a stack​

List your stacks​

Get a stack​

Delete a stack​

Retry a failed stack​

The Marketplace​

Authoring a template​

Visibility and publication​

Launching a marketplace template​

Listing marketplace templates​

Upgrading a stack​

What can be upgraded in place​

Preview before applying​

Applying an upgrade​

Next Steps​