# Blueprint Management (CIP-57)

## Overview

The Anvil API provides powerful endpoints for managing Cardano smart contract blueprints. These endpoints allow you to create, retrieve, update, and delete CIP-57 compliant blueprints in a standardized way. This is usually the compiled `plutus.json` file from an Aiken build.

{% hint style="warning" %}
**SECURITY NOTE**

All blueprint operations require an API key, which serves as your authentication credential and determines which blueprints you can access. The system maintains blueprint isolation between users, ensuring that:

* When you create a blueprint, it's associated with your API key
* When you search for blueprints, you only see blueprints created with your API key
* When you delete blueprints, you can only remove blueprints you own

This security model ensures that your smart contract blueprints remain private to your account while still enabling collaboration through controlled sharing mechanisms.
{% endhint %}

## Blueprint Management API Endpoints

| Endpoint                   | Method | Description                                                                                                                           | Required Parameters                        | Optional Parameters                                      |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | -------------------------------------------------------- |
| `/blueprints`              | POST   | Create or update a blueprint                                                                                                          | `blueprint`: CIP-57 compliant blueprint    | `refs`: Reference UTXOs                                  |
| `/blueprints`              | GET    | Find blueprints matching criteria                                                                                                     | None                                       | `title`, `version`, `limit`, `offset`, `sortBy`, `order` |
| `/blueprints`              | DELETE | Remove blueprints                                                                                                                     | `title`: Blueprint title                   | `version`: Blueprint version                             |
| `/blueprints/apply-params` | POST   | Apply parameters to validators - [See Documentation](/guides/smart-contract/smart-contract-utilities.md#apply-parameters-to-a-script) | `params`: Validator hash to params mapping | `blueprint`: CIP-57 blueprint (if not uploaded)          |

## Common Setup

The following setup is common to all blueprint operations:

```typescript
// Import your blueprint (typically from an Aiken build)
import plutusJson from "../hello-world/plutus.json" with { type: "json" };

// Setup API key and content type
const headers = {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

// Define the API endpoint
const blueprintsUrl = "https://preprod.api.ada-anvil.app/v2/services/blueprints";
```

## Creating or Updating Blueprints

Use the `POST` method to upload a new blueprint or update an existing one. The API automatically determines whether to create or update based on the blueprint's title and version.

```typescript
async function upsertBlueprint() {
  try {
    // Prepare the request body with your CIP-57 blueprint
    const input = { blueprint: plutusJson };
    
    const res = await fetch(blueprintsUrl, {
      method: "POST",
      body: JSON.stringify(input),
      headers,
    });
    
    const json = await res.json();
    
    // The response contains:
    // - jsonSchema: Generated JSON schema from the blueprint
    // - scriptAddresses: Record of validator hashes and their addresses
    // - blueprintId: ID of the created/updated blueprint
    console.log("json", JSON.stringify(json, null, 2));
  } catch (error) {
    console.log("error", error);
  }
}
```

## Finding Blueprints

Use the `GET` method to search for blueprints by title, version, or other criteria.

```typescript
async function findBlueprints() {
  try {
    const url = new URL(blueprintsUrl);
    
    // Optional search parameters
    url.searchParams.set("title", "cardano-forge/vesting-contract"); // Filter by title
    url.searchParams.set("version", "0.0.0"); // Filter by version
    // Additional optional parameters: limit, offset, sortBy, order
    
    const res = await fetch(url, {
      method: "GET",
      headers,
    });
    
    const json = await res.json();
    
    // The response contains:
    // - results: Array of matching blueprints
    // - total: Total count of matching blueprints
    console.log("json", JSON.stringify(json, null, 2));
  } catch (error) {
    console.log("error", error);
  }
}
```

## Deleting Blueprints

Use the `DELETE` method to remove blueprints from the system.

```typescript
async function deleteBlueprint() {
  try {
    const url = new URL(blueprintsUrl);
    
    // Required parameter
    url.searchParams.set("title", "cardano-forge/vesting-contract");
    
    // Optional parameter - if omitted, all versions with the specified title will be deleted
    url.searchParams.set("version", "0.0.0");
    
    const res = await fetch(url, {
      method: "DELETE",
      headers,
    });
    
    const json = await res.json();
    
    // The response contains:
    // - deleted: Array of strings identifying the deleted blueprints
    console.log("json", JSON.stringify(json, null, 2));
  } catch (error) {
    console.log("error", error);
  }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ada-anvil.io/guides/smart-contract/blueprint-management.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.