# Blueprint

URL: https://docs.hanzo.ai/docs/openapi/blueprint

> What a template costs to run, worked out before you deploy.

Also for this capability: **API** · [CLI](https://docs.hanzo.ai/docs/cli/blueprint) · [MCP](https://docs.hanzo.ai/docs/mcp-tools/blueprint) · [SDKs](https://docs.hanzo.ai/docs/sdks)

What a template costs to run, worked out before you deploy.

> [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides)

|                |                                        |
| -------------- | -------------------------------------- |
| **Base URL**   | `https://api.hanzo.ai`                 |
| **Operations** | 3                                      |
| **Auth**       | `Authorization: Bearer $HANZO_API_KEY` |

## Specification

> **HIP-1106 · Blueprint — The Priced Stack** — Draft · [read the specification →](https://github.com/hanzoai/hips/blob/7ed737180339cd05b5f2935eafe7f7b83d2449a2/HIPs/hip-1106-blueprint-priced-stack.md)

`/v1/blueprint` is what a template costs to run, worked out before you deploy.
Each deployable blueprint is a compose stack; this capability turns one into the
two things a deploying org and the console need — its SBOM, the bill of
container images the stack runs, and a compute-cost estimate, a per-hour rate
derived from the services' summed CPU and memory footprint through a documented
rate card. It is implemented in `hanzoai/cloud` at `apps/blueprint`.

### Motivation

A template economy needs a price that can be explained rather than merely
asserted. The rate this capability computes is what the platform shows as the
monthly cost per template AND the basis the deploy path meters the deploying org
on — which makes it the number the author royalty is taken from, so it has to
come from a real rate card, not a fabricated figure
(`apps/blueprint/blueprint.go:15-32`).

### Specification

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY are to be interpreted
as in RFC 2119.

#### §1 Reference content, no store

The blueprints are embedded in the binary (`embed.FS`) and validated once at
mount — a malformed fixture fails the mount closed, because a broken blueprint
must never reach a deploy sizing or a price card (`apps/blueprint/blueprint.go`,
`build`). There is no per-tenant state and no database; the capability owns no
store.

#### §2 Addresses

Three operations under `/v1/blueprint`. The list and health are typed.
`GET /v1/blueprint/sbom` is declared with prose beside the route instead: one
address answers two shapes at 200 — `?template=<id>` returns a bare estimate,
no parameter returns the batch — and a typed operation declares one Out, so
either shape would publish the other as a lie
(`apps/blueprint/blueprint.go:120-125`). Health is deliberately not JWT-gated,
because liveness must be probe-able; it also discloses the active rate card.

#### §3 The rate card is disclosed, not implied

An estimate carries the basis its rates came from, and the live card — after
the operator's env overlay, applied once at mount — is itself readable, so a
client that must explain a published price can (`apps/blueprint/estimate.go`).
This is the distinction from the sbom capability: that one stores a dependency
SBOM keyed by image digest — the packages INSIDE one image — while this one
derives the bill of IMAGES a stack runs and prices the footprint. Different
granularity, kept orthogonal.

#### §4 Tenancy, money, events, telemetry, stage, upstream

There is no tenant in the data: every caller reads the same embedded blueprints
and the same card. The capability is free (`plugin/blueprint/main.go`,
`cloud.Free`); the metering it feeds happens on the deploy path, against the
rate this capability computed. It publishes nothing to the bus. Beyond the
request span it emits structured log lines only. Stage `ga`: it is the platform
plane's pricing basis, part of the self-service core — the manifest row carries
no stage field yet, so the declaration here is what the row inherits when stage
lands in `manifest.App`. It derives from no OSS upstream; the blueprints it
embeds describe OSS stacks, which is data about them, not a fork of them.

### Rationale

The alternative is to price templates by hand, one number per template in a
catalog. That number cannot be explained, goes stale the day a stack adds a
service, and silently diverges from what the deploy path meters. Deriving the
price from the stack's own compose file through one disclosed card keeps the
shown price and the metered price the same computation.

### Security Considerations

The capability holds no secrets and no tenant data, so the exposure is
economic: a wrong implementation misprices compute. Understated, every deploy
of a template bills less than it costs and the author royalty is computed from
the wrong base; a tampered rate overlay does the same deliberately. The
controls are that the card is env-set by the operator, applied once at mount,
and disclosed on every estimate — a wrong price is at least a visible one, and
the fail-closed mount means a blueprint that cannot be parsed and priced is
never shown at all.

## Four surfaces

| Surface  | Reaches this capability as                        | Coverage                                                                  |
| -------- | ------------------------------------------------- | ------------------------------------------------------------------------- |
| **REST** | `blueprint` at its own prefix                     | 3 operations                                                              |
| **CLI**  | `hanzo blueprint …`                               | 3 of 3                                                                    |
| **SDK**  | `BlueprintApi` in every published client          | 3 methods                                                                 |
| **MCP**  | tool `blueprint` on `https://api.hanzo.ai/v1/mcp` | 2 operations, 1 under the document's own id — ask `describe` for the rest |

## Quickstart

```bash
export HANZO_API_KEY=sk-...   # console.hanzo.ai → API keys
```

Then the first call — a read that needs nothing but the key. `GET /v1/blueprint`, operation `get_blueprint`:

**CLI**

```bash
hanzo blueprint get
```

**SDK**

**.ts**

```ts
import { Configuration, BlueprintApi } from 'hanzoai';

const api = new BlueprintApi(new Configuration({ accessToken: process.env.HANZO_API_KEY }));
const { data } = await api.getBlueprint();
```

**.py**

```python
from hanzoai.cloud import ApiClient, Configuration
from hanzoai.cloud.api import BlueprintApi

client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"]))
result = BlueprintApi(client).get_blueprint()
```

**.go**

```go
cfg := hanzoai.NewConfiguration()
cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY"))
client := hanzoai.NewAPIClient(cfg)

resp, _, err := client.BlueprintAPI.GetBlueprint(context.Background()).Execute()
if err != nil {
	return err
}
```

**.rs**

```rust
use hanzo_client::apis::{configuration::Configuration, blueprint_api};

let mut cfg = Configuration::new();
cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok();

let result = blueprint_api::get_blueprint(&cfg, Default::default()).await?;
```

**.java**

```java
import ai.hanzo.cloud.ApiClient;
import ai.hanzo.cloud.api.BlueprintApi;

ApiClient client = new ApiClient();
client.setBearerToken(System.getenv("HANZO_API_KEY"));

var result = new BlueprintApi(client).getBlueprint();
```

**HTTP**

```bash
curl https://api.hanzo.ai/v1/blueprint \
  -H "Authorization: Bearer $HANZO_API_KEY"
```

**MCP**

MCP reaches **blueprint** through the `blueprint` tool, which names its 2 operations with its own verbs — this one among them, under a name only MCP declares. `describe` explains any of them:

```bash
curl -X POST https://api.hanzo.ai/v1/mcp \
  -H "Content-Type: application/json" \
  -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/call",
       "params": {
         "name": "describe",
         "arguments": {
           "op": "list_blueprints"
         }
       }
     }'
```

Answers `200` with `object` — ok.

## Endpoints

| Endpoint                                                                                        | What it does                                                                                  |
| ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| [`GET /v1/blueprint/health`](https://docs.hanzo.ai/docs/openapi/blueprint/get-blueprint-health) | Reports blueprint liveness and echoes the compute rate card in force.                         |
| [`GET /v1/blueprint/sbom`](https://docs.hanzo.ai/docs/openapi/blueprint/get-blueprint-sbom)     | A blueprint's bill of images and what running it costs                                        |
| [`GET /v1/blueprint`](https://docs.hanzo.ai/docs/openapi/blueprint/get-blueprint)               | Returns every deployable blueprint with its service count and estimated monthly compute cost. |

---

[All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)