API ReferenceHelp Center and Knowledge BaseDownload CLIGo to AppBook a Demo

Blueprints

get

Get extended package details

🔒 Requires the read:package permission

Authorizations
Query parameters
namestringRequired

The package name e.g. @bluebricks/aws-vpc

Example: @bluebricks/aws-vpc
versionstringOptional

The package version e.g. 1.2.3

Example: 1.2.3
Responses
200

Package info and bricks.json content

application/json
get
/api/v1/package
GET /api/v1/package?name=%40bluebricks%2Faws-vpc HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "package_info": {
    "name": "@bluebricks/aws-vpc",
    "version": "1.2.3",
    "url": "https://url.to.git.repo",
    "created": "2025-11-11T15:23:37.211Z",
    "updated": null,
    "is_latest": true,
    "enabler_email": "[email protected]",
    "verified_at": "2021-08-17T10:00:00Z",
    "description": "A package for blueprinting a VPC",
    "type": "blueprint",
    "iac_type": [
      "terraform"
    ],
    "tags": [
      "my-tag"
    ],
    "is_pre_release": true,
    "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
    "git_short_sha": "a1b2c3d4",
    "git_remote_url": "https://github.com/username/repository.git",
    "git_branch": "main",
    "git_subdir_path": "path/to/subdirectory",
    "owner": "[email protected]",
    "organization": "org_abCdeFghIjklMnmP",
    "enabled": true
  },
  "config": {
    "name": "@bluebricks/aws-vpc",
    "description": "A package for blueprinting a secure VPC",
    "version": "1.2.3",
    "tags": [
      "my-tag"
    ],
    "manifest_version": 1,
    "state": "managed",
    "repository": {
      "type": "text",
      "url": "text"
    },
    "props": {
      "ANY_ADDITIONAL_PROPERTY": {
        "type": "string",
        "description": "The name of the VPC",
        "default": "my-vpc",
        "value": "my-vpc1",
        "allowed_values": [
          "my-vpc"
        ],
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    },
    "computed": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "outs": {
      "ANY_ADDITIONAL_PROPERTY": {
        "type": "string",
        "description": "The VPC ID",
        "value": "my-vpc123",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    },
    "packages": [
      {
        "id": "s3",
        "name": "terraform-aws-s3",
        "version": "1.2.3",
        "props": {
          "region": {
            "value": "'us-west-2'"
          },
          "vpc_id": {
            "value": "Props.vpc_id ?? Data.vpc1.vpc_id"
          }
        },
        "path": "https://github.com/bb/vpc.git",
        "kind": "terraform",
        "ANY_ADDITIONAL_PROPERTY": "anything"
      }
    ],
    "native": {
      "type": "terraform",
      "version": "text",
      "path": "text",
      "state_path": "text",
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "package_children": [
    {
      "name": "@bluebricks/aws-vpc",
      "version": "1.2.3",
      "url": "https://url.to.git.repo",
      "created": "2025-11-11T15:23:37.211Z",
      "updated": null,
      "is_latest": true,
      "enabler_email": "[email protected]",
      "verified_at": "2021-08-17T10:00:00Z",
      "description": "A package for blueprinting a VPC",
      "type": "blueprint",
      "iac_type": [
        "terraform"
      ],
      "tags": [
        "my-tag"
      ],
      "is_pre_release": true,
      "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
      "git_short_sha": "a1b2c3d4",
      "git_remote_url": "https://github.com/username/repository.git",
      "git_branch": "main",
      "git_subdir_path": "path/to/subdirectory",
      "owner": "[email protected]",
      "organization": "org_abCdeFghIjklMnmP",
      "enabled": true
    }
  ]
}
post

Publish a bricks.json-based blueprint to the package registry. The package will be uploaded to the provided namespace.

If no namespace is provided, it will be uploaded to the organization namespace by default. This ensures that packages are properly organized and accessible within the appropriate scope.

🔒 Requires the create:package permission

Authorizations
Body
packagestring · binaryRequired

The package content, zipped

bricksstring · binaryRequired

The bricks.json file

statebooleanOptional

Whether the package includes initial state, e.g. true

Default: false
gitCommitHashstringOptional

The git commit hash of the package source

Example: 8f63e821f0df35c1f0c354c2ce15d5f8a65a6039
gitRemoteUrlstringOptional

The git remote url of the package repository

Example: https://github.com/username/repository.git
gitBranchstringOptional

The git branch name the package was created from

Example: main
gitSubdirPathstringOptional

The git subdirectory path of the package repository

Example: path/to/subdirectory
artifactHashstringOptional

SHA-256 hash of the artifact files for collision validation purposes (relevant only for packages of type artifact)

Example: ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015adPattern: ^[a-fA-F0-9]{64}$
Responses
200

Information about published package

application/json
post
/api/v1/package
POST /api/v1/package HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 311

{
  "package": "binary",
  "bricks": "binary",
  "state": false,
  "gitCommitHash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
  "gitRemoteUrl": "https://github.com/username/repository.git",
  "gitBranch": "main",
  "gitSubdirPath": "path/to/subdirectory",
  "artifactHash": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
}
{
  "name": "@bluebricks/aws-vpc",
  "version": "1.2.3",
  "url": "https://url.to.git.repo",
  "created": "2025-11-11T15:23:37.211Z",
  "updated": null,
  "is_latest": true,
  "enabler_email": "[email protected]",
  "verified_at": "2021-08-17T10:00:00Z",
  "description": "A package for blueprinting a VPC",
  "type": "blueprint",
  "iac_type": [
    "terraform"
  ],
  "tags": [
    "my-tag"
  ],
  "is_pre_release": true,
  "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
  "git_short_sha": "a1b2c3d4",
  "git_remote_url": "https://github.com/username/repository.git",
  "git_branch": "main",
  "git_subdir_path": "path/to/subdirectory",
  "owner": "[email protected]",
  "organization": "org_abCdeFghIjklMnmP"
}
get

List the available versions of a package

🔒 Requires the read:package permission

Authorizations
Query parameters
packagestringRequired

The package name e.g. @bluebricks/aws-vpc

Example: @bluebricks/aws-vpc
Responses
200

Package info and list of versions

application/json
get
/api/v1/package/versions
GET /api/v1/package/versions?package=%40bluebricks%2Faws-vpc HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "package_info": {
    "name": "@bluebricks/aws-vpc",
    "version": "1.2.3",
    "url": "https://url.to.git.repo",
    "created": "2025-11-11T15:23:37.211Z",
    "updated": null,
    "is_latest": true,
    "enabler_email": "[email protected]",
    "verified_at": "2021-08-17T10:00:00Z",
    "description": "A package for blueprinting a VPC",
    "type": "blueprint",
    "iac_type": [
      "terraform"
    ],
    "tags": [
      "my-tag"
    ],
    "is_pre_release": true,
    "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
    "git_short_sha": "a1b2c3d4",
    "git_remote_url": "https://github.com/username/repository.git",
    "git_branch": "main",
    "git_subdir_path": "path/to/subdirectory",
    "owner": "[email protected]",
    "organization": "org_abCdeFghIjklMnmP"
  },
  "versions": [
    {
      "version": "1.2.3",
      "is_pre_release": true,
      "is_latest": true,
      "iac_type": [
        "terraform"
      ],
      "tags": [
        "my-tag"
      ],
      "created": "2025-11-11T15:23:37.211Z",
      "description": null,
      "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
      "git_short_sha": "a1b2c3d4",
      "git_remote_url": "https://github.com/username/repository.git",
      "git_branch": "main",
      "git_subdir_path": "path/to/subdirectory",
      "enabled": true
    }
  ]
}
post

Search through published packages

🔒 Requires the read:package permission

Authorizations
Body
offsetnumberOptional

Results offset to allow pagination e.g. 10

Default: 0Example: 10
orderstringOptional

Specifies the order - ascending or descending - by which the returned list should be sorted e.g. ASC

limitnumberOptional

Results limit to allow pagination, e.g. 50

Default: 10Example: 10
querystringRequired

Search query e.g. blue*, *blue

sortstring · enumOptional

Specifies the attribute by which the returned list should be sorted

Possible values:
Responses
200

List of packages matching the query

application/json
post
/api/v1/package/search
POST /api/v1/package/search HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 71

{
  "offset": 10,
  "order": "text",
  "limit": 10,
  "query": "text",
  "sort": "created"
}
{
  "packages": [
    {
      "name": "@bluebricks/aws-vpc",
      "version": "1.2.3",
      "url": "https://url.to.git.repo",
      "created": "2025-11-11T15:23:37.211Z",
      "updated": null,
      "is_latest": true,
      "enabler_email": "[email protected]",
      "verified_at": "2021-08-17T10:00:00Z",
      "description": "A package for blueprinting a VPC",
      "type": "blueprint",
      "iac_type": [
        "terraform"
      ],
      "tags": [
        "my-tag"
      ],
      "is_pre_release": true,
      "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
      "git_short_sha": "a1b2c3d4",
      "git_remote_url": "https://github.com/username/repository.git",
      "git_branch": "main",
      "git_subdir_path": "path/to/subdirectory",
      "owner": "[email protected]",
      "organization": "org_abCdeFghIjklMnmP",
      "enabled": true
    }
  ],
  "results": 1,
  "total": 1
}
get

Provide the status of a specific package for the account. Mostly used to indicate if package is already enabled for an account

🔒 Requires the read:package permission

Authorizations
Query parameters
packagestringRequired

The package name e.g. @bluebricks/aws-vpc

Example: @bluebricks/aws-vpc
versionstringOptional

The package version e.g. 1.2.3

Example: 1.2.3
include_pre_releasebooleanOptional

Include pre-release packages e.g. false

Example: false
Responses
200

List of enabled versions of a package

application/json
get
/api/v1/package/status
GET /api/v1/package/status?package=%40bluebricks%2Faws-vpc HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "name": "@bluebricks/aws-vpc",
    "version": "1.2.3",
    "is_pre_release": true,
    "created": "2025-11-11T15:23:37.211Z",
    "enabler": "text"
  }
]
get

Validate package properties

🔒 Requires the read:package permission

Authorizations
Query parameters
packagestringRequired

The package name e.g. @bluebricks/aws-vpc

Example: @bluebricks/aws-vpc
versionstringOptional

The package version e.g. 1.2.3

Example: 1.2.3
validate_propsstring[]Required

List of properties to validate if they are customizable e.g. ["bucket_name.region", "vpc_id"]

Responses
200

Validation result for package properties

application/json
get
/api/v1/package/validation/customizable
GET /api/v1/package/validation/customizable?package=%40bluebricks%2Faws-vpc&validate_props=text HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "statusCode": 200,
  "error": "text",
  "message": "All provided properties are customizable for the package '@bluebricks/aws-vpc",
  "details": {
    "package": "@bluebricks/aws-vpc",
    "version": "1.2.3",
    "suggestion": "You can proceed with customizing the provided properties"
  }
}
post

Enable package version/s within the org

🔒 Requires the update:package permission

Authorizations
Body
packagestringRequired

The package name e.g. @bluebricks/aws-vpc

Example: @bluebricks/aws-vpc
versionstringOptional

The package version e.g. 1.2.3

Example: 1.2.3
Responses
200

Package version/s enabled

application/json
post
/api/v1/package/enable
POST /api/v1/package/enable HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "package": "@bluebricks/aws-vpc",
  "version": "1.2.3"
}
{
  "enabled": true,
  "versions": [
    "1.2.3"
  ]
}
post

Disable package version/s within the org

🔒 Requires the update:package permission

Authorizations
Body
packagestringRequired

The package name e.g. @bluebricks/aws-vpc

Example: @bluebricks/aws-vpc
versionstringOptional

The package version e.g. 1.2.3

Example: 1.2.3
Responses
200

Package version/s disabled

application/json
post
/api/v1/package/disable
POST /api/v1/package/disable HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "package": "@bluebricks/aws-vpc",
  "version": "1.2.3"
}
{
  "enabled": false,
  "versions": [
    "1.2.3"
  ]
}
post

Install package on remote cloud

🔒 Requires the create:deployment permission

Authorizations
Query parameters
validate_onlybooleanOptional

Validate package for installation without execution

Default: false
Body
packagestringRequired

The package name, e.g. @bluebricks/postgres. Optional if planId is provided

Example: @bluebricks/aws-vpc
versionstringOptional

The package version e.g. 1.2.3

Example: 1.2.3
forcebooleanOptional

Force installation without approval

planOnlybooleanOptional

Plan the installation/uninstall without executing

Default: false
driftDetectionbooleanOptional

Enable drift detection for the deployment

Default: false
envstringOptional

Target environment for installation

Default: The default environment of the organization
slugstringOptional

Provides a slug for a newly created deployment. Cannot be specified if deployment was provided

deploymentstringOptional

Identify a previous deployments using its ID or slug for the same package in the same environment to share state and slug e.g. postgres-prod or 5ecbb18d-04c7-4298-b550-ab12bf661477

Responses
200

Created task id for installation process or validate installation

application/json
Responseone of

Created task id for installation process or validate installation

or
post
/api/v1/package/install
POST /api/v1/package/install HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 232

{
  "package": "@bluebricks/aws-vpc",
  "version": "1.2.3",
  "force": true,
  "planOnly": false,
  "driftDetection": false,
  "env": "The default environment of the organization",
  "slug": "text",
  "props": {
    "password": "$postgres.prodPass"
  },
  "deployment": "text"
}
{
  "deployment": "123e4567-e89b-12d3-a456-426614174000",
  "task": "123e4567-e89b-12d3-a456-426614174000"
}
post

Uninstall package from cloud

🔒 Requires the create:deployment permission

Authorizations
Body
deploymentstringRequired

Deployment ID or slug to target for uninstall e.g. aws-single-ec2-development-1 or 797746e4-07a0-4aed-bb15-89dd9a7c413a

planOnlybooleanOptional

Plan the installation/uninstall without executing

Default: false
Responses
200

Created task id for uninstall process

application/json
post
/api/v1/package/uninstall
POST /api/v1/package/uninstall HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 38

{
  "deployment": "text",
  "planOnly": false
}
{
  "deployment": "123e4567-e89b-12d3-a456-426614174000",
  "task": "123e4567-e89b-12d3-a456-426614174000"
}
get

Load package by name and version

🔒 Requires the read:package permission

Authorizations
Path parameters
packageNamestringRequired

The package name e.g. @bluebricks/aws-vpc

Example: @bluebricks/aws-vpc
versionstringRequired

The package version e.g. 1.2.3

Example: 1.2.3
Responses
200

Presigned URL for package download

application/json
get
/api/v1/package/{packageName}/{version}
GET /api/v1/package/{packageName}/{version} HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "url": "https://example.com"
}
get

List packages used by organization

🔒 Requires the read:package permission

Authorizations
Query parameters
allbooleanOptional

When true, returns all packages including those that were already deployed. When false, returns only not-deployed packages.

latestbooleanOptional

When true, returns only the latest version for each package

sortstring · enumOptional

Specifies the attribute by which the returned list should be sorted e.g. name

Default: blueprint_metadata.downloaded_atPossible values:
offsetnumberOptional

Results offset to allow pagination e.g. 10

Default: 0Example: 10
orderstringOptional

Specifies the order - ascending or descending - by which the returned list should be sorted e.g. ASC

limitnumber · min: 3 · max: 1000Optional

Results limit to allow pagination, e.g. 50

Default: 20Example: 10
filterstringOptional

Structure: [key1=value1,key2=value2&value3]

searchstringOptional

Enables searching within the list for package names that match a particular query e.g. sns

include_pre_releasebooleanOptional

Include pre-release packages e.g. false

Example: false
Responses
200

Last completed deployments for an environment

application/json
get
/api/v1/packages
GET /api/v1/packages HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "packages": [
    {
      "name": "@bluebricks/aws-vpc",
      "version": "1.2.3",
      "url": "https://url.to.git.repo",
      "created": "2025-11-11T15:23:37.211Z",
      "updated": null,
      "is_latest": true,
      "enabler_email": "[email protected]",
      "verified_at": "2021-08-17T10:00:00Z",
      "description": "A package for blueprinting a VPC",
      "type": "blueprint",
      "iac_type": [
        "terraform"
      ],
      "tags": [
        "my-tag"
      ],
      "is_pre_release": true,
      "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
      "git_short_sha": "a1b2c3d4",
      "git_remote_url": "https://github.com/username/repository.git",
      "git_branch": "main",
      "git_subdir_path": "path/to/subdirectory",
      "owner": "[email protected]",
      "organization": "org_abCdeFghIjklMnmP",
      "deployments": 3,
      "active_git_trigger": {
        "id": "123e4567-e89b-12d3-a456-42661417400",
        "git_ref": "main",
        "path": "path/to/subdirectory",
        "repo": "organization/repository"
      },
      "blueprint_metadata": {
        "published_environment": [
          {
            "id": "f27d96be-c486-4075-a926-0ee96775119e",
            "slug": "production-europe",
            "name": "Production Europe",
            "color": "#0000ff",
            "allow_pre_release": false,
            "is_default": true,
            "is_active": true,
            "is_deleted": true,
            "created": "2025-11-11T15:23:37.211Z",
            "users": [
              {
                "id": "prov0|1234567890",
                "name": "John Doe",
                "email": "[email protected]",
                "nickname": "JD",
                "picture": "https://example.com/profile.jpg",
                "roles": [
                  {
                    "id": "rol_abCdeFghIjklMnmP",
                    "name": "Admin",
                    "description": "Role for managing Admin permissions"
                  }
                ]
              }
            ],
            "cloud_account": {
              "id": "123e4567-e89b-12d3-a456-426614174000",
              "name": "Production Europe",
              "provider": "aws",
              "slug": "production-europe",
              "is_active": true,
              "is_deleted": false,
              "created": "2025-11-11T15:23:37.211Z",
              "cloud_account": "123456789012",
              "assume_role_arn": "arn:aws:iam::123456789012:role/Bluebricks-Setup-BluebricksReadOnlyRole-123abc456DEF",
              "external_id": "abcdef-ghijklm",
              "cloud_config": {
                "service_account_email": "sa@project_id.iam.gserviceaccount.com",
                "scopes": "https://www.googleapis.com/auth/cloud-platform",
                "cluster_name": "text",
                "service_account_namespace": "text",
                "service_account_name": "text",
                "cluster_oidc_url": "https://example.com",
                "ANY_ADDITIONAL_PROPERTY": "anything"
              },
              "is_primary": true,
              "profile": "secrets-manager"
            }
          }
        ],
        "downloaded_by": "text",
        "downloaded_at": null
      }
    }
  ],
  "total": 1,
  "published": 1,
  "drafts": 1
}
post

Compare package file hashes to identify changed packages

🔒 Requires the read:package permission

Authorizations
Body
Responses
200

Comparison result with changed and unchanged packages

application/json
post
/api/v1/package-changes
POST /api/v1/package-changes HTTP/1.1
Host: api.bluebricks.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 76

{
  "packages": {
    "ANY_ADDITIONAL_PROPERTY": [
      {
        "version": "1.2.3",
        "hash": "text"
      }
    ]
  }
}
{
  "changed": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "@bluebricks/aws-vpc",
      "version": "1.2.3",
      "hash": "text",
      "previous_hash": null,
      "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
      "git_short_sha": "a1b2c3d4",
      "git_remote_url": "https://github.com/username/repository.git",
      "git_branch": "main",
      "git_subdir_path": "path/to/subdirectory"
    }
  ],
  "unchanged": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "@bluebricks/aws-vpc",
      "version": "1.2.3",
      "hash": "text",
      "previous_hash": null,
      "git_commit_hash": "8f63e821f0df35c1f0c354c2ce15d5f8a65a6039",
      "git_short_sha": "a1b2c3d4",
      "git_remote_url": "https://github.com/username/repository.git",
      "git_branch": "main",
      "git_subdir_path": "path/to/subdirectory"
    }
  ],
  "total": 1
}
PreviousAuthNextCloud Accounts

Last updated

Was this helpful?