---
id: platform/blueprints
title: Manage Blueprints
description: Connect a render.yaml file to Bex, preview its resources, control synchronization, and disconnect without deleting workloads.
keywords: [bex, blueprints, render.yaml, infrastructure as code, sync]
last_updated: 2026-09-23
---

A Git-connected Blueprint tracks a repository, branch, and YAML file and records
synchronizations of its declared resources. Use it to manage an application's
services, datastores, and configuration together.

The [App resources and render.yaml guide](./app-resource.md) covers manifest
grammar and direct validation/apply. This guide covers the persistent Blueprint
resource and its lifecycle. Neither workflow copies existing application data.

## Preview and create

Prepare and commit `render.yaml`, connect the repository through
[GitHub integration](./github-integration.md), and select the intended workspace.
Blueprint creation requires an authorized developer/admin and configured
control-plane storage and Git fetching. Private repositories need a valid grant.

Using the credentials from [API authentication](./api.md), preview the exact
repository, branch, and path before creating the Blueprint:

```bash
curl --fail-with-body --silent --show-error \
  -X POST "$BEX_API_URL/v1/blueprints/preview" \
  -H "Authorization: Bearer $BEX_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"ownerId":"YOUR_WORKSPACE_ID","repo":"https://github.com/acme/shop","branch":"main","path":"render.yaml"}'
```

Replace the example values. Review validation errors, required secret inputs,
resource changes, and pricing/capacity implications. A preview is not a deploy.
Paths must be clean repository-relative `.yaml` or `.yml` paths. If both legacy
`bex.yml` and `render.yaml` exist, specify the intended file explicitly.

Create with `POST /v1/blueprints` using the same fields and an optional `name`.
Creation applies the manifest; it is not just registration. Inputs for declared
secret placeholders can be supplied through `envVarValues` as supported by the
preview/create flow—keep them out of committed YAML and logs.

Store the returned Blueprint `id`. Inspect the Blueprint and its sync history,
then check the actual deployments and datastore readiness. Successful
configuration application does not establish that every workload is healthy.

## Synchronize changes

| Action | REST endpoint |
| --- | --- |
| List workspace Blueprints | `GET /v1/blueprints?ownerId=…` |
| Inspect one | `GET /v1/blueprints/{id}?ownerId=…` |
| Inspect sync history | `GET /v1/blueprints/{id}/syncs?ownerId=…` |
| Manually sync | `POST /v1/blueprints/{id}/sync` with `{"ownerId":"…"}` |
| Disable automatic sync | `PATCH /v1/blueprints/{id}` with `{"ownerId":"…","autoSync":false}` |

New Git-connected Blueprints enable automatic sync. Delivery still depends on
working Git integration. Blueprint auto-sync and each service's auto-deploy
setting govern different operations; inspect both when a push changes behavior.

A manual Git sync resolves the tracked branch to a commit and reads the file
at that commit. **A fetch failure or an unavailable Git fetcher fails the sync;
it does not apply the stored manifest as a fallback.** Check the sync's recorded
commit and resolve repository access problems before retrying. An explicitly
supplied manifest is a separate sync path and does not claim a Git commit.

Only one apply can run for a given Blueprint at a time. A competing sync or
disconnect can return `409` with `BLUEPRINT_SYNC_BUSY`; wait for the active sync
to settle, then inspect its result before retrying.

Reapplying unchanged declarations is a no-op for unchanged resources. Changed
services deploy, and validation errors must be resolved before applying. Runtime
failures during a multi-resource apply can leave partial progress; inspect the
resulting resources before retrying. Protected-environment changes can require
an explicit confirmation phrase.

## Change ownership or remove resources

Manage a resource from one authoritative manifest. Dashboard/API changes can be
replaced by the next sync if the manifest declares conflicting values. Review
existing settings before adopting a resource into a Blueprint; defaults can
differ from its current configuration.

Removing an entry from YAML does not delete the resource. To retire it, remove
its declaration and delete the resource explicitly after reviewing data and
backup requirements. Leaving the declaration can recreate it on a later sync.

`DELETE /v1/blueprints/{id}?ownerId=…` disconnects the Blueprint and clears its
ownership. Workloads remain; empty Blueprint-created project/environment
groupings may be reclaimed. Disconnection does not necessarily disable each
service's own Git auto-deployment. Check those settings separately.

For failed builds or releases, use [deployment stages](./how-deploys-work.md) and
[logs](./logging.md). For path-related failures, see [monorepos](./monorepos.md).