{ "openapi": "3.0.2", "info": { "title": "Blueprint Manifest API", "version": "4.8.0", "description": "Service to create and install Blueprint Manifest files" }, "tags": [ { "name": "Jobs", "description": "Manage Export and Import Jobs" }, { "name": "Export", "description": "Export a Blueprint Manifest" }, { "name": "Import", "description": "Install or update a Blueprint Manifest" }, { "name": "Manifests", "description": "Manage installed Manifests" }, { "name": "Blueprints", "description": "Manage Custom and Installed Blueprints" }, { "name": "Installations", "description": "Manage installation jobs" }, { "name": "Marketplace Listings", "description": "Manage marketplace listings for blueprints" }, { "name": "Marketplace Listing Versions", "description": "Manage versions for marketplace listings" }, { "name": "Patches", "description": "Manage blueprint patches for mass rollouts" }, { "name": "Uniqueness Criteria", "description": "Configure per-org field sets used to match existing resources during install" } ], "security": [ { "EpilotAuth": [] } ], "servers": [ { "url": "https://blueprint-manifest.sls.epilot.io" } ], "paths": { "/v1/blueprint-manifest/jobs/{job_id}": { "get": { "operationId": "getJob", "summary": "getJob", "description": "Get the current status of a blueprint (export or import)", "deprecated": true, "tags": [ "Jobs" ], "parameters": [ { "$ref": "#/components/parameters/JobID" } ], "responses": { "200": { "description": "Current status of the blueprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" } } } } } } }, "/v1/blueprint-manifest/jobs:createExport": { "post": { "operationId": "createExport", "summary": "createExport", "description": "Creates a new Export Job with a list of available resources to export from the passed root resource.\n\nMultiple root resources can be added by calling this multiple times with the same jobId\n", "deprecated": true, "tags": [ "Export" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/ResourceNodeType" }, "id": { "type": "string" } }, "required": [ "type", "id" ] }, "minItems": 1 }, "jobId": { "$ref": "#/components/schemas/JobID" }, "isExportingMultipleResources": { "type": "boolean", "description": "Temporary flag to indicate if multiple resources are being exported" }, "pipelineId": { "type": "string", "description": "Pipeline ID selected when doing the sandbox sync" }, "manifestId": { "type": "string", "description": "ID of the installed manifest to load the resource addresses from" } }, "required": [ "resources" ] } } } }, "responses": { "200": { "description": "Created Export Job ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "$ref": "#/components/schemas/JobID" } } } } } } } } }, "/v1/blueprint-manifest/jobs/{job_id}:exportManifest": { "post": { "operationId": "exportManifest", "summary": "exportManifest", "description": "Triggers exporting a manifest file using selected resoruce ids for a job created with `createExportJob`", "deprecated": true, "tags": [ "Export" ], "parameters": [ { "$ref": "#/components/parameters/JobID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "selectedResourceIds": { "description": "An array of resource IDs to export", "type": "array", "items": { "type": "string" } }, "resourceName": { "type": "string", "example": "journey_HouseConnectionJourney" }, "metadata": { "type": "object", "properties": { "markdown": { "type": "object", "properties": { "manifest": { "type": "string" }, "preinstall": { "type": "string" }, "postinstall": { "type": "string" } } }, "docs_link": { "type": "string" }, "source_blueprint_name": { "type": "string" }, "source_blueprint_slug": { "type": "string" }, "source_blueprint_version": { "type": "string" } } }, "isExportingMultipleResources": { "type": "boolean", "description": "Temporary flag to indicate if multiple resources are being exported" }, "generateAISummary": { "type": "boolean", "default": false }, "language": { "type": "string", "enum": [ "en", "de" ] } }, "required": [ "resourceName", "selectedResourceIds" ] } } } }, "responses": { "200": { "description": "Export Job ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "$ref": "#/components/schemas/JobID" } } } } } } } } }, "/v1/blueprint-manifest:uploadManifest": { "post": { "operationId": "uploadManifest", "summary": "uploadManifest", "description": "Create pre-signed S3 URL to upload a manifest file.\n", "tags": [ "Import" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UploadFilePayload" } } } }, "responses": { "201": { "description": "Pre-signed URL for POST / PUT upload", "content": { "application/json": { "schema": { "type": "object", "properties": { "s3ref": { "$ref": "#/components/schemas/S3Reference" }, "upload_url": { "type": "string", "format": "url", "example": "https://epilot-dev-blueprints.s3.eu-central-1.amazonaws.com/templates/document.pdf" } } } } } } } } }, "/v1/blueprint-manifest/jobs:createPlan": { "post": { "operationId": "createPlan", "summary": "createPlan", "description": "Creates a new import job from an uploaded manifest file and returns the plan.\n\nCreates an updated plan for an installed manifest when `manifest_id` is passed\n", "deprecated": true, "tags": [ "Import" ], "requestBody": { "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "s3ref": { "allOf": [ { "description": "s3ref of manifest file uploaded via `uploadManifest`" }, { "$ref": "#/components/schemas/S3Reference" } ] }, "manifest_id": { "allOf": [ { "description": "Update an existing manifest (optional)" }, { "$ref": "#/components/schemas/ManifestID" } ] }, "job_id": { "allOf": [ { "description": "Continue a previous job" }, { "$ref": "#/components/schemas/JobID" } ] }, "source": { "allOf": [ { "description": "Source of the manifest" }, { "$ref": "#/components/schemas/ManifestSource" } ] }, "resourcesToIgnore": { "type": "array", "items": { "type": "string" }, "description": "List of resources to ignore changes for" }, "resourceReplacements": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceReplacement" }, "description": "List of resource replacements to apply during import" }, "deployedFrom": { "type": "object", "properties": { "sourceOrganizationId": { "type": "string" }, "sourceManifestId": { "type": "string" }, "sourceOrganizationType": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "sourceOrganizationId", "sourceManifestId", "sourceOrganizationType" ] } }, "required": [ "s3ref" ] }, { "type": "object", "deprecated": true, "properties": { "manifestFilePath": { "deprecated": true, "description": "Manifest s3 key uploaded via `uploadManifest`", "type": "string" }, "manifest_id": { "allOf": [ { "description": "Update an existing manifest (optional)" }, { "$ref": "#/components/schemas/ManifestID" } ] }, "job_id": { "allOf": [ { "description": "Continue a previous job" }, { "$ref": "#/components/schemas/JobID" } ] }, "source": { "allOf": [ { "description": "Source of the manifest" }, { "$ref": "#/components/schemas/ManifestSource" } ] }, "resourcesToIgnore": { "type": "array", "items": { "type": "string" }, "description": "List of resources to ignore changes for" }, "resourceReplacements": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceReplacement" }, "description": "List of resource replacements to apply during import" }, "deployedFrom": { "type": "object", "properties": { "sourceOrganizationId": { "type": "string" }, "sourceManifestId": { "type": "string" }, "sourceOrganizationType": { "type": "string", "enum": [ "sandbox", "production" ] } }, "required": [ "sourceOrganizationId", "sourceManifestId", "sourceOrganizationType" ] } }, "required": [ "manifestFilePath" ] } ] } } } }, "responses": { "200": { "description": "Created Import Job ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "type": "string", "example": "4854bb2a-94f9-424d-a968-3fb17fb0bf89" } } } } } } } } }, "/v1/blueprint-manifest/jobs/{job_id}:applyPlan": { "post": { "operationId": "applyPlan", "summary": "applyPlan", "description": "Apply a plan returned by `createPlan`.", "deprecated": true, "tags": [ "Import" ], "parameters": [ { "$ref": "#/components/parameters/JobID" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "resourcesToIgnore": { "type": "array", "items": { "type": "string" }, "description": "List of resources to ignore changes for" }, "resourceReplacements": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceReplacement" }, "description": "List of resource replacements to apply during import" } } } } } }, "responses": { "200": { "description": "Applied Import Job ID", "content": { "application/json": { "schema": { "type": "object", "properties": { "jobId": { "$ref": "#/components/schemas/JobID" } } } } } } } } }, "/v1/blueprint-manifest/manifests": { "get": { "operationId": "listInstalledManifests", "summary": "listInstalledManifests", "description": "List Blueprint Manifests installed to the organization", "deprecated": true, "tags": [ "Manifests" ], "responses": { "200": { "description": "Installed Blueprint Manifests in the organization", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ManifestItem" } } } } } } } } } }, "/v1/blueprint-manifest/manifests/{manifest_id}": { "get": { "operationId": "getManifest", "summary": "getManifest", "description": "Get installed Manifest by ID", "deprecated": true, "tags": [ "Manifests" ], "parameters": [ { "in": "path", "required": true, "name": "manifest_id", "schema": { "$ref": "#/components/schemas/ManifestID" } } ], "responses": { "200": { "description": "Installed Blueprint Manifest in the Organization", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" } } } } } }, "put": { "operationId": "updateManifest", "summary": "updateManifest", "description": "Update an installed manifest\n", "deprecated": true, "tags": [ "Manifests" ], "parameters": [ { "in": "path", "required": true, "name": "manifest_id", "schema": { "$ref": "#/components/schemas/ManifestID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutManifestPayload" } } } }, "responses": { "200": { "description": "The updated Manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" } } } } } }, "delete": { "operationId": "deleteManifest", "summary": "deleteManifest", "description": "Remove installed manifest from the org\n\nNote that this does not delete the installed resources of the Manifest!\n", "deprecated": true, "tags": [ "Manifests" ], "parameters": [ { "in": "path", "required": true, "name": "manifest_id", "schema": { "$ref": "#/components/schemas/ManifestID" } } ], "responses": { "200": { "description": "The deleted Manifest", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Manifest" } } } } } } }, "/v2/blueprint-manifest/blueprints": { "get": { "operationId": "listBlueprints", "summary": "listBlueprints", "description": "List Custom and Installed Blueprints", "tags": [ "Blueprints" ], "parameters": [ { "name": "archived", "in": "query", "description": "Filter blueprints by archived status. If true, returns only archived blueprints. If false or not provided, returns only non-archived blueprints.", "required": false, "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Blueprints", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Blueprint" } } } } } } } } }, "post": { "operationId": "createBlueprint", "summary": "createBlueprint", "description": "Create a Blueprint", "tags": [ "Blueprints" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blueprint" } } } }, "responses": { "200": { "description": "Created Blueprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blueprint" } } } } } } }, "/v2/blueprint-manifest/blueprints:marketplace": { "get": { "operationId": "listInstalledMarketplaceBlueprints", "summary": "listInstalledMarketplaceBlueprints", "description": "List installed Marketplace Blueprints for the organization.\nWhen multiple blueprints have the same slug, returns only the most recently created one.\n", "tags": [ "Blueprints" ], "responses": { "200": { "description": "Installed Marketplace Blueprints", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/InstalledMarketplaceBlueprintItem" } } } } } } } } } }, "/v2/blueprint-manifest/blueprints:pre-install": { "post": { "operationId": "preInstallBlueprint", "summary": "preInstallBlueprint", "description": "Pre-install a Blueprint based on a blueprint file. Format-agnostic: the engine is detected from the uploaded archive, so this endpoint accepts both Terraform exports and signed V3 packages. The returned preview's `sync_engine` says which install endpoint to call next. An archive that is neither a Terraform export nor a validly signed V3 package is rejected with 400.", "tags": [ "Blueprints" ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "blueprint_file": { "type": "string", "description": "URL to the blueprint zip file" }, "source_blueprint_type": { "type": "string", "enum": [ "marketplace" ] }, "slug": { "type": "string", "description": "Slug to enforce in this blueprint. Used in marketplace blueprints to keep it consistent with webflow." } } } } } }, "responses": { "200": { "description": "Blueprint preview data for UI display", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintPreview" } } } }, "400": { "description": "Invalid request body, or an archive that no install engine accepts" } } } }, "/v2/blueprint-manifest/blueprints:preview/{preview_id}": { "get": { "operationId": "getBlueprintPreview", "summary": "getBlueprintPreview", "description": "Get Blueprint Preview by ID", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "preview_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Blueprint Preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintPreview" } } } }, "404": { "description": "Blueprint Preview not found" } } } }, "/v2/blueprint-manifest/blueprint:install": { "post": { "operationId": "installBlueprint", "deprecated": true, "summary": "installBlueprint", "description": "Kick off a new blueprint installation job. Returns 202 Accepted with Location header pointing to the job resource\n", "tags": [ "Blueprints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_org_id": { "type": "string" }, "source_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "source_blueprint_file": { "type": "string", "description": "URL to the blueprint zip file" }, "destination_org_id": { "type": "string" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "source_auth_token": { "type": "string", "description": "Auth token with access to the source org. Required for cross-org auto-verification when the caller's bearer token belongs to the destination org." }, "destination_auth_token": { "type": "string", "description": "Auth token with access to the destination org. Defaults to the caller's bearer token." }, "options": { "$ref": "#/components/schemas/BlueprintInstallationJobOptions" }, "mode": { "type": "string", "enum": [ "simple", "advanced" ], "description": "Installation mode" }, "source_blueprint_type": { "type": "string", "enum": [ "marketplace" ] }, "slug": { "type": "string", "description": "Slug to enforce in this blueprint. Used in marketplace blueprints to keep it consistent with webflow." }, "auto_enable_features": { "type": "boolean", "description": "If true, automatically enable required features in the destination org before installing" } }, "required": [ "mode" ] } } } }, "responses": { "202": { "description": "Blueprint installation job started", "headers": { "Location": { "description": "URL to poll the job", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" } } } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}": { "get": { "operationId": "getBlueprint", "summary": "getBlueprint", "description": "Get Blueprint by ID", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "responses": { "200": { "description": "Blueprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blueprint" } } } } } }, "put": { "operationId": "updateBlueprint", "summary": "updateBlueprint", "description": "Update a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blueprint" } } } }, "responses": { "200": { "description": "Updated Blueprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blueprint" } } } } } }, "delete": { "operationId": "deleteBlueprint", "summary": "deleteBlueprint", "description": "Delete a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "responses": { "200": { "description": "Deleted Blueprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Blueprint" } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/notes": { "post": { "operationId": "addBlueprintNote", "summary": "addBlueprintNote", "description": "Append an internal note to a blueprint. `id`, `created_at` and `created_by`\nare stamped server-side from the caller, so notes cannot be backdated or\nattributed to someone else. Existing notes are never modified.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Plain-text note body. Must not be blank.", "minLength": 1 } } } } } }, "responses": { "201": { "description": "The created note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintNote" } } } }, "400": { "description": "Blank note text", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/notes/{note_id}": { "patch": { "operationId": "updateBlueprintNote", "summary": "updateBlueprintNote", "description": "Rewrite the text of an existing internal note. The note keeps its position in\nthe list along with `created_at` and `created_by`, so an edit cannot reassign\nauthorship; `updated_at` is stamped server-side.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "required": true, "name": "note_id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Plain-text note body. Must not be blank.", "minLength": 1 } } } } } }, "responses": { "200": { "description": "The updated note", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintNote" } } } }, "400": { "description": "Blank note text", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "404": { "description": "Blueprint or note not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } }, "delete": { "operationId": "deleteBlueprintNote", "summary": "deleteBlueprintNote", "description": "Remove a single internal note from a blueprint.", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "required": true, "name": "note_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The blueprint's remaining notes", "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintNote" } } } } } } }, "404": { "description": "Blueprint or note not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/validate": { "post": { "operationId": "validateBlueprint", "deprecated": true, "summary": "validateBlueprint", "description": "Start a blueprint validation job. Validates Terraform for the blueprint (all types).\nReturns 202 Accepted with job_id. Poll GET /jobs/{job_id} for status, valid, and errors.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "responses": { "202": { "description": "Validation job started", "headers": { "Location": { "description": "URL to poll the job", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" } } } } } }, "404": { "description": "Blueprint not found" } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}:verify": { "post": { "operationId": "verifyBlueprint", "summary": "verifyBlueprint", "description": "Start a blueprint verification job. Compares resource configurations between a source org\nand a destination org to verify that a sync/install was successful.\nReturns 202 Accepted with job_id. Poll GET /jobs/{job_id} for status, summary, and resource_results.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "source_org_id", "source_blueprint_id", "destination_org_id", "destination_blueprint_id" ], "properties": { "source_org_id": { "type": "string", "description": "Organization ID of the source org" }, "source_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "destination_org_id": { "type": "string", "description": "Organization ID of the destination org" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "source_auth_token": { "type": "string", "description": "Auth token with access to the source org (e.g. pipeline token). If not provided, the caller's bearer token is used for both orgs." }, "destination_auth_token": { "type": "string", "description": "Auth token with access to the destination org. Required for cross-org verification when the caller token only has access to the source org. If not provided, the caller's bearer token is used for both orgs." }, "installation_job_id": { "allOf": [ { "$ref": "#/components/schemas/BlueprintJobID" } ], "description": "Optional install job this verification is checking. If omitted, the latest destination blueprint installation job is used when available." }, "sync_engine": { "type": "string", "enum": [ "terraform", "v3" ], "description": "Optional install engine hint. Usually inferred from installation_job_id." } } } } } }, "responses": { "202": { "description": "Verification job started", "headers": { "Location": { "description": "URL to poll the job", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" } } } } } }, "404": { "description": "Blueprint not found" } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/patches:detect": { "post": { "operationId": "detectPatchChanges", "deprecated": true, "summary": "detectPatchChanges", "description": "Detect changes between the current state of a blueprint's resources and its tfstate baseline.\nReturns field-level diffs for resources that have been modified since the blueprint was last installed/exported.\n", "tags": [ "Patches" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "source_org_id": { "type": "string", "description": "Organization ID of the source org where changes were made" }, "dest_org_id": { "type": "string", "description": "Organization ID of a destination org (used to load tfstate baseline)" }, "dest_blueprint_id": { "type": "string", "description": "Blueprint ID in the destination org (used to locate tfstate in S3)" }, "rollout_id": { "type": "string", "description": "ID of the mass rollout" } } } } } }, "responses": { "200": { "description": "Detected changes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetectChangesResult" } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/patches": { "post": { "operationId": "createPatch", "deprecated": true, "summary": "createPatch", "description": "Create a new patch for a blueprint.", "tags": [ "Patches" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blueprint_id", "rollout_id", "source_org_id", "name", "resources" ], "properties": { "blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "rollout_id": { "type": "string" }, "source_org_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/PatchResourceDiff" } }, "changelog": { "type": "string" } } } } } }, "responses": { "201": { "description": "Patch created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintPatch" } } } } } }, "get": { "operationId": "listPatches", "deprecated": true, "summary": "listPatches", "description": "List all patches for a blueprint.", "tags": [ "Patches" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "responses": { "200": { "description": "List of patches", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintPatch" } } } } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/patches/{patch_id}": { "get": { "operationId": "getPatch", "deprecated": true, "summary": "getPatch", "description": "Get a patch by ID, including per-org execution results.", "tags": [ "Patches" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "required": true, "name": "patch_id", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Patch details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintPatchWithResults" } } } }, "404": { "description": "Patch not found" } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/patches/{patch_id}:apply": { "post": { "operationId": "applyPatch", "deprecated": true, "summary": "applyPatch", "description": "Apply a patch to a single destination org.", "tags": [ "Patches" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "required": true, "name": "patch_id", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "org_id", "org_name", "dest_blueprint_id" ], "properties": { "org_id": { "type": "string" }, "org_name": { "type": "string" }, "dest_blueprint_id": { "type": "string" }, "dest_org_id": { "type": "string" }, "destination_auth_token": { "type": "string", "description": "Auth token with access to the destination org (e.g. pipeline token)" } } } } } }, "responses": { "200": { "description": "Patch execution result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgPatchExecution" } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/patches/{patch_id}/orgs/{org_id}:retry": { "post": { "operationId": "retryPatchOrg", "deprecated": true, "summary": "retryPatchOrg", "description": "Retry a failed patch execution for a specific org.", "tags": [ "Patches" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "required": true, "name": "patch_id", "schema": { "type": "string" } }, { "in": "path", "required": true, "name": "org_id", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "org_name": { "type": "string" }, "dest_blueprint_id": { "type": "string" }, "destination_auth_token": { "type": "string" } } } } } }, "responses": { "200": { "description": "Retry execution result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrgPatchExecution" } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}:export": { "post": { "operationId": "exportBlueprint", "deprecated": true, "summary": "exportBlueprint", "description": "Kick off a new blueprint export job. Returns 202 Accepted with Location header pointing to the job resource.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "destination_org_id": { "type": "string" }, "destination_blueprint_id": { "type": "string" }, "validate": { "type": "boolean", "description": "When true, run terraform validate before creating the export zip. If validation fails, the job will be marked as FAILED with errors." } } } } } }, "responses": { "202": { "description": "Blueprint export job started", "headers": { "Location": { "description": "URL to poll the job", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" } } } } } } } } }, "/v2/blueprint-manifest/marketplace/slugs": { "get": { "operationId": "listMarketplaceSlugs", "summary": "listMarketplaceSlugs", "description": "List all available marketplace blueprint slugs from Webflow CMS.\nReturns cached results when available.\n", "tags": [ "Blueprints" ], "responses": { "200": { "description": "List of marketplace slugs", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "slug": { "type": "string", "description": "The installation slug identifier for the blueprint (used for publishing).", "example": "wallbox_b2c" }, "marketplace_slug": { "type": "string", "description": "The marketplace page slug for the Webflow CMS item (used for display).", "example": "wallbox-b2c" }, "version": { "type": "string", "example": "v1.0.0" }, "name": { "type": "string", "example": "Wallbox B2C" }, "installation_link": { "type": "string", "example": "https://portal.epilot.cloud/app/blueprints/install/marketplace/wallbox_b2c?s3Ref=https://example.com/blueprint.zip" } } } } } } } } } } } }, "/v2/blueprint-manifest/blueprints:publish": { "post": { "operationId": "publishBlueprint", "summary": "publishBlueprint", "description": "Publish a blueprint to the marketplace. Exports the blueprint, uploads it to file-api with public access, and updates the Webflow CMS listing.\n", "tags": [ "Blueprints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blueprint_id", "slug" ], "properties": { "blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "slug": { "type": "string", "description": "The marketplace installation slug for the Webflow CMS item" }, "version": { "type": "string", "description": "The version string to set on the marketplace CMS item (e.g. \"1.0.0\")" }, "name": { "type": "string", "description": "The display name for the blueprint on the marketplace CMS item" } } } } } }, "responses": { "202": { "description": "Blueprint publish job started", "headers": { "Location": { "description": "URL to poll the job", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" } } } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}:format-description": { "post": { "operationId": "formatBlueprintDescription", "summary": "formatBlueprintDescription", "description": "Format a blueprint description as markdown using AI.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "text" ], "properties": { "text": { "type": "string", "description": "Plain text to format as markdown" } } } } } }, "responses": { "200": { "description": "Successfully formatted description", "content": { "application/json": { "schema": { "type": "object", "properties": { "markdown": { "type": "string", "description": "AI-formatted markdown content" } } } } } } } } }, "/v2/blueprint-manifest/blueprints:suggest-resources": { "post": { "operationId": "suggestBlueprintResources", "summary": "suggestBlueprintResources", "description": "Suggest resources to add to a blueprint based on a natural-language prompt.\n\nWalks anchor resource types in priority order (journey > workflow_definition >\nautomation_flow > schema > entity-backed types) and returns matches per\nanchor using each upstream API's text search. Suggestions are marked\n`is_root: true` so callers can pass `add_dependencies=true` to\nbulkAddBlueprintResources and have transitive dependencies resolved\nserver-side — which means a single matched journey can stand in for its\nfull product/schema/template bundle.\n\nNo side effects on the blueprint — the caller persists the chosen resources\nvia the existing create/bulk-add endpoints.\n", "tags": [ "Blueprints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestBlueprintResourcesRequest" } } } }, "responses": { "200": { "description": "Suggested resources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SuggestBlueprintResourcesResponse" } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/resources": { "post": { "operationId": "addBlueprintResource", "summary": "addBlueprintResource", "description": "Add a resource to a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "query", "name": "add_dependencies", "schema": { "type": "boolean", "default": false, "description": "Whether to add this resource dependencies to the blueprint automatically" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintResource" } } } }, "responses": { "200": { "description": "Added Blueprint Resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } }, "skipped": { "type": "array", "description": "Resources that were dropped during enrichment instead of being added", "items": { "$ref": "#/components/schemas/SkippedBlueprintResource" } }, "errors": { "type": "array", "description": "Non-fatal dependency extraction failures encountered while enriching, deduplicated and capped. The listed resources were still added; some of their dependencies may be missing.", "items": { "$ref": "#/components/schemas/FormattedError" } }, "total_errors": { "type": "integer", "description": "Total distinct dependency errors, before the cap applied to `errors`" }, "errors_truncated": { "type": "boolean", "description": "Whether `errors` omits some of the distinct errors counted by `total_errors`" } } } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/resources:syncDependencies": { "post": { "operationId": "syncDependencies", "summary": "syncDependencies", "description": "Sync dependencies of all root resources in a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "query", "required": false, "name": "trigger", "description": "What initiated the sync. Automated triggers (`pre_sync`,\n`post_revert`) are side effects of an operation the activity\nfeed already shows on its own row, so they are excluded from\nthe audit log — same policy as validate/verify.\n", "schema": { "type": "string", "enum": [ "manual", "pre_sync", "post_revert" ], "default": "manual" } } ], "responses": { "202": { "description": "Dependencies sync job started", "headers": { "Location": { "description": "URL to poll the job", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" } } } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/resources/bulk": { "post": { "operationId": "bulkAddBlueprintResources", "summary": "bulkAddBlueprintResources", "description": "Bulk Add resources in a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "query", "name": "add_dependencies", "schema": { "type": "boolean", "default": false, "description": "Whether to add this resource dependencies to the blueprint automatically" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } }, "responses": { "200": { "description": "Bulk updated Blueprint Resources", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } }, "skipped": { "type": "array", "description": "Resources that were dropped during enrichment instead of being added", "items": { "$ref": "#/components/schemas/SkippedBlueprintResource" } }, "errors": { "type": "array", "description": "Non-fatal dependency extraction failures encountered while enriching, deduplicated and capped. The listed resources were still added; some of their dependencies may be missing.", "items": { "$ref": "#/components/schemas/FormattedError" } }, "total_errors": { "type": "integer", "description": "Total distinct dependency errors, before the cap applied to `errors`" }, "errors_truncated": { "type": "boolean", "description": "Whether `errors` omits some of the distinct errors counted by `total_errors`" } } } } } } } }, "put": { "operationId": "bulkUpdateBlueprintResources", "summary": "bulkUpdateBlueprintResources", "description": "Bulk update resources in a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } }, "responses": { "200": { "description": "Bulk updated Blueprint Resources", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } } } } } }, "delete": { "operationId": "bulkDeleteBlueprintResources", "summary": "bulkDeleteBlueprintResources", "description": "Bulk delete resources in a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResourceID" } } } } }, "responses": { "200": { "description": "Bulk deleted Blueprint Resources", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } } } } } } }, "/v2/blueprint-manifest/blueprints/{blueprint_id}/resources/{resource_id}": { "put": { "operationId": "updateBlueprintResource", "summary": "updateBlueprintResource", "description": "Update a resource in a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "required": true, "name": "resource_id", "schema": { "$ref": "#/components/schemas/BlueprintResourceID" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintResource" } } } }, "responses": { "200": { "description": "Updated Blueprint Resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } } } } } }, "delete": { "operationId": "deleteBlueprintResource", "summary": "deleteBlueprintResource", "description": "Delete a resource from a Blueprint", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "required": true, "name": "resource_id", "schema": { "$ref": "#/components/schemas/BlueprintResourceID" } } ], "responses": { "200": { "description": "Deleted Blueprint Resource", "content": { "application/json": { "schema": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } } } } } } }, "/v2/blueprint-manifest/jobs": { "get": { "operationId": "listBlueprintJobs", "summary": "listBlueprintJobs", "description": "List all blueprint jobs", "tags": [ "Jobs" ], "responses": { "200": { "description": "Blueprint jobs", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer", "example": 1 }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintJob" } } } } } } } } } }, "/v2/blueprint-manifest/jobs/{job_id}": { "get": { "operationId": "getBlueprintJob", "summary": "getBlueprintJob", "description": "Poll the current state of a job. Serves both Terraform (v2) and V3-engine jobs —\ncheck `sync_engine` (`terraform` | `v3`) to tell them apart. V3 jobs additionally\nexpose live `resource_progress[]`. V3 single-install and bulk-install child jobs\nare polled here.\n", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "required": true, "name": "job_id", "schema": { "$ref": "#/components/schemas/BlueprintJobID" } } ], "responses": { "200": { "description": "Job status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintJob" } } } } } } }, "/v2/blueprint-manifest/jobs/{job_id}:continue": { "post": { "operationId": "continueInstallationJob", "summary": "continueInstallationJob", "description": "Resume an installation job that is paused at `status: \"WAITING_USER_ACTION\"` after\nplanning. Works for both Terraform and V3 jobs. Not needed for V3 installs created\nwith `auto_apply: true` (including all bulk-install child jobs), which apply\nwithout pausing.\n\nAlso resumes a V3 install paused at `status: \"REAUTH_REQUIRED\"`, where the\ncaller's credentials could not safely cover another run. The job keeps its\n`job_id`, so resuming continues from the operation-log checkpoint rather than\nre-applying completed work. The request's bearer token becomes the destination\ncredential; for a cross-org install whose SOURCE credential also expired, send a\nfreshly scoped source token as `source_auth_token` — the destination bearer is not\na valid substitute for it.\n", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "required": true, "name": "job_id", "schema": { "$ref": "#/components/schemas/BlueprintJobID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContinueInstallationJobRequest" } } } }, "responses": { "200": { "description": "Blueprint installation job continued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintInstallationJob" } } } } } } }, "/v2/blueprint-manifest/jobs/{job_id}:retry": { "post": { "operationId": "retryInstallationJob", "summary": "retryInstallationJob", "description": "Retry a finished V3 installation job whose status is `FAILED` or\n`PARTIAL_SUCCESS`. Starts a fresh install job (new `job_id`) with the same\nsource/destination and `auto_apply: true` — no `:continue` call is needed.\nThe plan phase re-resolves every resource: already-synced resources no-op,\nso effectively only the failed resources are re-applied.\n\nMust be called by a user of the destination org (where the job lives); the\ncaller's bearer token is used as the destination token. The plan reuses the\nmanifest persisted by the original install, so no source-org access is\nrequired. The original job's `options` (ignored resources, sync_notes) are\nreused when present; older jobs without persisted options fall back to the\ndestination blueprint's `ignored_resource_addresses`.\n", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "required": true, "name": "job_id", "schema": { "$ref": "#/components/schemas/BlueprintJobID" } } ], "responses": { "202": { "description": "Retry install job started", "headers": { "Location": { "description": "Path to poll the resulting job: GET /v2/blueprint-manifest/jobs/{job_id}", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" } } } } } }, "400": { "description": "Job is not a retryable V3 installation job" }, "404": { "description": "Job not found" } } } }, "/v2/blueprint-manifest/jobs/{job_id}:cancel": { "post": { "operationId": "cancelBlueprintJob", "summary": "cancelBlueprintJob", "description": "Cancel a blueprint job if it is still running.", "tags": [ "Jobs" ], "parameters": [ { "in": "path", "required": true, "name": "job_id", "schema": { "$ref": "#/components/schemas/BlueprintJobID" } } ], "responses": { "200": { "description": "Blueprint job cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintJob" } } } } } } }, "/v1/blueprints/{blueprint_id}/marketplace-listing": { "post": { "operationId": "createMarketplaceListing", "summary": "createMarketplaceListing", "description": "Create a marketplace listing for a blueprint. Returns 409 if one already exists.", "tags": [ "Marketplace Listings" ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } } } }, "responses": { "201": { "description": "Marketplace listing created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListing" } } } }, "409": { "description": "Listing already exists for this blueprint" } } }, "get": { "operationId": "getMarketplaceListing", "summary": "getMarketplaceListing", "description": "Get marketplace listing for a blueprint including all versions", "tags": [ "Marketplace Listings" ], "parameters": [ { "name": "blueprint_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Marketplace listing with versions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MarketplaceListing" }, { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceListingVersion" } }, "has_publishable_draft": { "type": "boolean" } } } ] } } } }, "404": { "description": "Listing not found" } } } }, "/v1/marketplace-listings": { "get": { "operationId": "listMarketplaceListings", "summary": "listMarketplaceListings", "description": "List all marketplace listings for the authenticated organization", "tags": [ "Marketplace Listings" ], "security": [ { "EpilotAuth": [] } ], "responses": { "200": { "description": "List of marketplace listings", "content": { "application/json": { "schema": { "type": "object", "properties": { "listings": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceListing" } } } } } } } } } }, "/v1/marketplace-listings/{listing_id}": { "get": { "operationId": "getMarketplaceListingById", "summary": "getMarketplaceListingById", "description": "Get marketplace listing by listing ID including all versions", "tags": [ "Marketplace Listings" ], "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Marketplace listing with versions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/MarketplaceListing" }, { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceListingVersion" } }, "has_publishable_draft": { "type": "boolean" } } } ] } } } }, "404": { "description": "Listing not found" } } }, "patch": { "operationId": "updateMarketplaceListing", "summary": "updateMarketplaceListing", "description": "Update listing-level fields", "tags": [ "Marketplace Listings" ], "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListingUpdate" } } } }, "responses": { "200": { "description": "Updated marketplace listing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListing" } } } }, "404": { "description": "Listing not found" } } }, "delete": { "operationId": "deleteMarketplaceListing", "summary": "deleteMarketplaceListing", "description": "Delete listing and all versions", "tags": [ "Marketplace Listings" ], "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "Listing deleted" }, "404": { "description": "Listing not found" } } } }, "/v1/marketplace-listings/{listing_id}/versions": { "post": { "operationId": "createMarketplaceListingVersion", "summary": "createMarketplaceListingVersion", "description": "Create a draft version; auto-snapshots resources, requiredFeatures, recommendedApps from current blueprint", "tags": [ "Marketplace Listing Versions" ], "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "201": { "description": "Draft version created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListingVersion" } } } }, "404": { "description": "Listing not found" } } }, "get": { "operationId": "listMarketplaceListingVersions", "summary": "listMarketplaceListingVersions", "description": "List all versions for a listing, newest first", "tags": [ "Marketplace Listing Versions" ], "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of versions", "content": { "application/json": { "schema": { "type": "object", "properties": { "versions": { "type": "array", "items": { "$ref": "#/components/schemas/MarketplaceListingVersion" } } } } } } } } } }, "/v1/marketplace-listings/{listing_id}/versions/{version_id}": { "patch": { "operationId": "updateMarketplaceListingVersion", "summary": "updateMarketplaceListingVersion", "description": "Update updateNote, requiredFeatures, or recommendedApps on a draft version", "tags": [ "Marketplace Listing Versions" ], "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "update_note": { "type": "string", "nullable": true }, "required_features": { "type": "array", "items": { "type": "string" } }, "recommended_apps": { "type": "array", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Updated version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListingVersion" } } } }, "400": { "description": "Cannot update non-draft version" }, "404": { "description": "Version not found" } } } }, "/v1/marketplace-listings/{listing_id}/versions/{version_id}/publish": { "post": { "operationId": "publishMarketplaceListingVersion", "summary": "publishMarketplaceListingVersion", "description": "Publish a draft version; archives the previous live version", "tags": [ "Marketplace Listing Versions" ], "parameters": [ { "name": "listing_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "version_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "version_name" ], "properties": { "version_name": { "type": "string" }, "update_note": { "type": "string", "nullable": true } } } } } }, "responses": { "200": { "description": "Published version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketplaceListingVersion" } } } }, "400": { "description": "Version not publishable or version_name already taken" }, "404": { "description": "Version not found" } } } }, "/v3/blueprint-manifest/blueprints/{blueprint_id}:publish": { "post": { "operationId": "publishBlueprintV3", "summary": "publishBlueprintV3", "description": "Starts an asynchronous V3 publication. The result is a signed, portable package; poll the existing blueprint job endpoint for completion.\n\nBy default this only builds the package and stores it privately for download. Creating or\noverwriting the public marketplace listing is opt-in via `publish_to_marketplace`.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "publish_to_marketplace": { "type": "boolean", "default": false, "description": "When true, upload the package with public access and create or overwrite the\nblueprint's Webflow CMS listing. Leave unset for a download-only package build.\n" } } } } } }, "responses": { "202": { "description": "Blueprint export job started", "headers": { "Location": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "job_id" ], "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" } } } } } } } } }, "/v3/blueprint-manifest/blueprints:pre-install": { "post": { "operationId": "preInstallBlueprintV3", "summary": "preInstallBlueprintV3", "description": "Validates a signed V3 package and returns the destination-specific resource plan used by the install UI.", "tags": [ "Blueprints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "blueprint_file" ], "properties": { "blueprint_file": { "type": "string", "description": "S3 key of a V3 blueprint package previously uploaded through uploadManifest" }, "source_blueprint_type": { "type": "string", "enum": [ "marketplace" ] }, "slug": { "type": "string", "description": "Marketplace slug to preserve across updates" } } } } } }, "responses": { "200": { "description": "Destination-specific V3 blueprint preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BlueprintPreview" } } } }, "400": { "description": "Invalid request or unsupported V3 package" }, "404": { "description": "Blueprint package not found" } } } }, "/v3/blueprint-manifest/blueprint:install": { "post": { "operationId": "installBlueprintV3", "summary": "installBlueprintV3", "description": "Install a blueprint into a single destination org using the V3 engine (direct API\ncalls, no Terraform). Creates resources in topological order with global ID\nreplacement and supports checkpoint-based resume on failure.\n\n**Lifecycle (how to drive an install to completion):**\n1. `POST /v3/blueprint-manifest/blueprint:install` returns `{ job_id }` (202).\n2. Poll the job with `GET /v2/blueprint-manifest/jobs/{job_id}` — V3 jobs are\n served by the same v2 jobs endpoints as Terraform jobs and are identified by\n `sync_engine: \"v3\"`. Watch `status` and `resource_progress[]`.\n3. If `auto_apply` is `false` (default), the job pauses at\n `status: \"WAITING_USER_ACTION\"` after planning. Resume it with\n `POST /v2/blueprint-manifest/jobs/{job_id}:continue`.\n4. If `auto_apply` is `true`, the engine applies automatically after plan +\n snapshot — no `:continue` call is needed. This is what the bulk-install worker\n uses; to install into many orgs at once prefer `POST .../bulk-installs`.\n\nFor cross-org installs, pass `destination_auth_token` (the destination org's\ntoken); reads use the caller's bearer token, writes use that token.\n", "tags": [ "Blueprints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "required": [ "source_org_id", "source_blueprint_id", "destination_org_id" ] }, { "required": [ "source_blueprint_file", "destination_org_id" ] } ], "properties": { "source_org_id": { "type": "string" }, "source_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "source_blueprint_file": { "type": "string", "description": "S3 key to the blueprint zip file" }, "destination_org_id": { "type": "string" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "destination_auth_token": { "type": "string", "description": "Auth token for the destination org. Required for cross-org installs where the caller's token belongs to the source org. Defaults to the caller's bearer token." }, "source_blueprint_type": { "type": "string", "enum": [ "marketplace" ] }, "options": { "$ref": "#/components/schemas/BlueprintInstallationJobOptions" }, "slug": { "type": "string", "description": "Slug for marketplace blueprint consistency" }, "auto_apply": { "type": "boolean", "description": "When `true`, the install skips the manual plan-approval step and applies\nstraight after plan + snapshot succeed (no `:continue` call needed).\nDefaults to `false`. Used internally by the bulk-install worker.\n", "default": false }, "session_credentials": { "type": "object", "description": "Lets the install refresh the caller's session on its own, so a run that\noutlives the ~60 minute token lifetime continues without the user present.\nHeld server-side for the job's lifetime, referenced from the state machine\nrather than embedded in it, and deleted when the job finishes.\n\nOptional. Without it an install that outruns its token pauses at\n`status: \"REAUTH_REQUIRED\"` and waits to be resumed through\n`POST /v2/blueprint-manifest/jobs/{job_id}:continue`.\n\nBounded by the refresh token itself (18 hours), not unlimited.\n", "required": [ "refresh_token", "client_id" ], "properties": { "refresh_token": { "type": "string", "format": "password", "description": "Cognito refresh token for the caller, scoped to the source org." }, "client_id": { "type": "string", "description": "The Cognito app client the refresh token was issued for. Required because\nepilot provisions one user pool and app client per organization at\nruntime, so the service cannot derive it.\n" }, "pipeline_id": { "type": "string", "description": "Cross-org installs only. The destination credential is not a Cognito\nsession — it is minted from the refreshed source session through\nsandbox-api, so it is re-derived per continuation instead of stored.\n" } } } } }, "examples": { "sameOrgPlanThenContinue": { "summary": "Same-org install, manual approval (default)", "value": { "source_org_id": "source-org-id", "source_blueprint_id": "11111111-1111-1111-1111-111111111111", "destination_org_id": "source-org-id" } }, "crossOrgAutoApply": { "summary": "Cross-org install, applied automatically", "value": { "source_org_id": "source-org-id", "source_blueprint_id": "11111111-1111-1111-1111-111111111111", "destination_org_id": "dest-org-id", "destination_auth_token": "destination-org-token", "auto_apply": true } } } } } }, "responses": { "202": { "description": "V3 install job started", "headers": { "Location": { "description": "Path to poll the resulting job: GET /v2/blueprint-manifest/jobs/{job_id}", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" } } } } } }, "400": { "description": "Missing required source or destination fields", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/v3/blueprint-manifest/blueprints/{blueprint_id}/deployments/{job_id}:restore": { "post": { "operationId": "restoreBlueprintDeploymentV3", "summary": "restoreBlueprintDeploymentV3", "description": "Roll a deployment back to its pre-install state. Two phases:\n\n 1. Upsert — re-applies the captured payloads via snapshot-api's\n `:restore` (server-side; runs config-engine.apply with captured\n target ids pre-seeded). Skipped for pure-create deployments\n whose snapshot was empty.\n 2. Delete sweep — for lineage rows of this blueprint instance not\n present in the snapshot's captured set, deletes the live\n resource via the type's adapter. Co-ownership / drift /\n no-delete-capability skip the entry with the corresponding\n reason.\n\nResolves `(blueprint_id, job_id)` to the entry in\n`Blueprint.deployments[]` and reads its `snapshot_id` and\n`destination_blueprint_id` — the caller never needs to handle\nsnapshot ids directly.\n\nAsync — returns 202 with a job id. Poll the job to track progress.\nThe restore holds its own per-instance lock (`active_restore_job_id`),\nseparate from `installation_status`. Starting a restore is rejected with\n409 when another restore already holds that lock, or when an install is\nrunning (`installation_status === 'IN_PROGRESS'`). Keeping the two locks\ndistinct keeps installs and reverts decoupled: an in-flight or failed\nrestore never overwrites `installation_status`, which keeps reflecting\nthe actual install outcome (and drives the install badge in the\nBlueprints overview) throughout the revert.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/BlueprintJobID" } } ], "responses": { "202": { "description": "Restore job started", "headers": { "Location": { "description": "URL to poll the job", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" }, "blueprint_instance_id": { "$ref": "#/components/schemas/BlueprintID" }, "snapshot_id": { "type": "string" } } } } } }, "400": { "description": "Deployment has no snapshot, or the snapshot is not in a `completed` state." }, "404": { "description": "Blueprint not found, or no deployment with the given job_id on this blueprint." }, "409": { "description": "Another install or restore is in flight for this blueprint instance." } } } }, "/v3/blueprint-manifest/blueprints/{blueprint_id}/deployments/{job_id}/restore-preview": { "get": { "operationId": "getRestorePreview", "summary": "getRestorePreview", "description": "Computes what would happen if the user triggered a restore on this\ndeployment, without performing any writes. The forecast uses the\nsnapshot's captured resources (when present) plus the current lineage\nstate plus per-adapter gates (co-ownership, no-delete-capability,\nheuristic-match, drift when wired).\n\nIdempotent and side-effect free. Safe to call repeatedly. The result\nmay shift between calls if operators edit destination resources or\nanother blueprint adopts a shared resource in the meantime.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "name": "job_id", "required": true, "description": "The install job whose deployment is being previewed.", "schema": { "$ref": "#/components/schemas/BlueprintJobID" } } ], "responses": { "200": { "description": "Predicted outcome. `failed`-action items are absent here — the\npreview can't forecast errors.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RestoreOutcome" } } } }, "404": { "description": "Blueprint or deployment not found." } } } }, "/v3/blueprint-manifest/blueprints/{blueprint_id}/deployments/{job_id}:health-check": { "post": { "operationId": "triggerDeploymentHealthCheckV3", "summary": "triggerDeploymentHealthCheckV3", "description": "Starts a read-only health scan of the resources this deployment's\nblueprint instance tracks in the destination org (see\ndocs/rfcs/RFC-org-health-check.md, Phase 0). Checks:\n\n - live readability — every lineage-tracked resource is read back\n via its adapter; tracked-but-unreadable resources are flagged.\n - referential integrity — destination payloads containing\n unreplaced source-org ids, or references to tracked resources\n that are not readable.\n - install completeness — install operations whose final attempt\n ended `failed` or `skipped`, with their rejection reasons.\n\nAsync — returns 202 immediately with a `running` report stub. Poll\nthe health-report endpoint until `status` is `completed` or\n`failed`. Never mutates any resource.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "name": "job_id", "required": true, "description": "The install job whose deployment is being checked.", "schema": { "$ref": "#/components/schemas/BlueprintJobID" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_org_id": { "type": "string", "description": "Source/sandbox org to deep-compare entity mappings against." }, "source_auth_token": { "type": "string", "description": "Read token for the source org. Never persisted; used only for this scan." } } } } } }, "responses": { "202": { "description": "Health check started", "headers": { "Location": { "description": "URL to poll the health report", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentHealthReport" } } } }, "404": { "description": "Blueprint not found, or no deployment with the given job_id on this blueprint." } } } }, "/v3/blueprint-manifest/blueprints/{blueprint_id}/deployments/{job_id}/health-report": { "get": { "operationId": "getDeploymentHealthReportV3", "summary": "getDeploymentHealthReportV3", "description": "Returns the most recent health report produced for this deployment\nby the `:health-check` endpoint. Idempotent and side-effect free.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "name": "blueprint_id", "required": true, "schema": { "$ref": "#/components/schemas/BlueprintID" } }, { "in": "path", "name": "job_id", "required": true, "schema": { "$ref": "#/components/schemas/BlueprintJobID" } } ], "responses": { "200": { "description": "Latest health report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeploymentHealthReport" } } } }, "404": { "description": "No health report exists for this deployment yet." } } } }, "/v3/blueprint-manifest/blueprints/{blueprint_id}/lineage": { "get": { "operationId": "getBlueprintLineageV3", "summary": "getBlueprintLineageV3", "description": "Returns the lineage registry entries for a blueprint's resources in the current org.\nShows the mapping between source lineage IDs and target resource IDs.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "required": true, "name": "blueprint_id", "schema": { "$ref": "#/components/schemas/BlueprintID" } } ], "responses": { "200": { "description": "Lineage entries for the blueprint", "content": { "application/json": { "schema": { "type": "object", "properties": { "total": { "type": "integer" }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/LineageEntry" } } } } } } } } } }, "/v3/blueprint-manifest/bulk-installs": { "post": { "operationId": "createBulkInstallV3", "summary": "createBulkInstallV3", "description": "Install one source blueprint into many destination organizations in a single\nrequest. The server schedules child V3 installs with `auto_apply=true` and caps\nactive installs at `max_concurrency`. Per-target failures are isolated and\nretryable; they do not stop the remaining targets.\n\nEach target carries its own write-only `destination_auth_token` (org-scoped).\nTokens are passed to the worker via Step Functions input only — they are never\npersisted in DynamoDB nor returned by any endpoint.\n", "tags": [ "Blueprints" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInstallCreateRequest" }, "examples": { "twoTargets": { "summary": "Install one blueprint into two orgs", "value": { "source_org_id": "source-org-id", "source_blueprint_id": "11111111-1111-1111-1111-111111111111", "max_concurrency": 2, "options": { "resources_to_ignore": [ "epilot-product_product.foo" ] }, "targets": [ { "destination_org_id": "dest-org-1", "destination_auth_token": "token-for-org-1" }, { "destination_org_id": "dest-org-2", "destination_blueprint_id": "22222222-2222-2222-2222-222222222222", "destination_auth_token": "token-for-org-2" } ] } } } } } }, "responses": { "202": { "description": "Bulk install accepted and scheduled", "headers": { "Location": { "description": "URL to poll the bulk install", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInstall" } } } }, "400": { "description": "Validation error — missing `source_blueprint_id`, empty/oversized `targets`\n(1–100), duplicate `destination_org_id`, missing per-target\n`destination_auth_token`, or `max_concurrency` out of range (1–5).\n", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } } } } }, "/v3/blueprint-manifest/bulk-installs/{bulk_job_id}": { "get": { "operationId": "getBulkInstallV3", "summary": "getBulkInstallV3", "description": "Returns the bulk install parent with aggregate status and counts. Scoped by the\ncaller org as `source_org_id`. Target rows are not included — use the targets\nendpoint to page through them.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "name": "bulk_job_id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Bulk install parent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInstall" } } } }, "404": { "description": "Bulk install not found for the caller org" } } } }, "/v3/blueprint-manifest/bulk-installs/{bulk_job_id}/targets": { "get": { "operationId": "listBulkInstallTargetsV3", "summary": "listBulkInstallTargetsV3", "description": "Pages through the bulk install's target rows. Each row hydrates its latest child\ninstall job (`job_ids.at(-1)`) with the standard V3 job shape (`events[]`,\n`resource_progress[]`) so callers can inspect per-resource progress and errors.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "name": "bulk_job_id", "required": true, "schema": { "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 10 } }, { "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of target rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInstallTargetList" } } } }, "404": { "description": "Bulk install not found for the caller org" } } } }, "/v3/blueprint-manifest/bulk-installs/{bulk_job_id}/targets/{destination_org_id}:retry": { "post": { "operationId": "retryBulkInstallTargetV3", "summary": "retryBulkInstallTargetV3", "description": "Retries a single failed target. Allowed only for `FAILED` and `PARTIAL_SUCCESS`\ntargets. Starts a new child install with `auto_apply=true`, appends its job id to\n`job_ids`, and reuses the same target row. Only the destination auth token may be\nsupplied for the new attempt; source/destination identifiers are immutable.\n", "tags": [ "Blueprints" ], "parameters": [ { "in": "path", "name": "bulk_job_id", "required": true, "schema": { "type": "string" } }, { "in": "path", "name": "destination_org_id", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "destination_auth_token" ], "properties": { "destination_auth_token": { "type": "string", "description": "Write-only auth token for the destination org used for the new attempt." } } } } } }, "responses": { "200": { "description": "Updated target row with hydrated latest child job", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkInstallTarget" } } } }, "400": { "description": "Target is not in a retryable (`FAILED`/`PARTIAL_SUCCESS`) state." }, "404": { "description": "Bulk install or target not found for the caller org." }, "409": { "description": "The target was concurrently claimed by another retry (already in progress)." } } } }, "/v1/blueprint-manifest/uniqueness-criteria": { "get": { "operationId": "listUniquenessCriteria", "summary": "listUniquenessCriteria", "description": "List all custom uniqueness criteria configured for the caller's organization.\nThese overrides are applied during install (V2 and V3) when matching incoming\nresources against existing ones in the destination org, replacing the default\nper-resource-type field set with the caller's chosen fields (AND-combined).\n", "tags": [ "Uniqueness Criteria" ], "responses": { "200": { "description": "All configured criteria for the org", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/UniquenessCriteria" } }, "defaults": { "type": "object", "description": "Built-in default uniqueness fields per resource type, as used by\nthe install engines when no custom criteria are configured.\n", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "readonly_types": { "type": "array", "description": "Resource types whose criteria are fixed by epilot and cannot be\ncustomized (writes are rejected). Shown read-only in the UI.\n", "items": { "type": "string" } } } } } } } } } }, "/v1/blueprint-manifest/uniqueness-criteria/{resource_type}": { "parameters": [ { "in": "path", "required": true, "name": "resource_type", "schema": { "$ref": "#/components/schemas/UniquenessCriteriaResourceType" } } ], "get": { "operationId": "getUniquenessCriteria", "summary": "getUniquenessCriteria", "description": "Get the configured uniqueness criteria for a specific resource type, if any.", "tags": [ "Uniqueness Criteria" ], "responses": { "200": { "description": "Configured criteria for the resource type", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniquenessCriteria" } } } }, "404": { "description": "No custom criteria configured (defaults will be used)" } } }, "put": { "operationId": "putUniquenessCriteria", "summary": "putUniquenessCriteria", "description": "Set or replace the uniqueness criteria for a resource type. The provided fields\nmust be valid attributes on the resource's schema (the UI typically loads the\nschema to populate options). All listed fields are AND-combined during matching.\n", "tags": [ "Uniqueness Criteria" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "fields" ], "properties": { "fields": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "propagated_to": { "type": "array", "description": "Org IDs this rule was also applied to (the UI's \"Also apply to\"\nselection). Stored so the selection survives reloads; each target\norg still holds its own criteria row.\n", "items": { "type": "string" } } } } } } }, "responses": { "200": { "description": "Stored criteria", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UniquenessCriteria" } } } }, "400": { "description": "Invalid resource type or field list" } } }, "delete": { "operationId": "deleteUniquenessCriteria", "summary": "deleteUniquenessCriteria", "description": "Remove the custom criteria for a resource type, reverting to the default fields.", "tags": [ "Uniqueness Criteria" ], "responses": { "204": { "description": "Criteria deleted (defaults will be used)" } } } } }, "components": { "schemas": { "UniquenessCriteriaResourceType": { "type": "string", "description": "Resource type for which custom uniqueness criteria can be configured.", "enum": [ "emailtemplate", "product", "price", "tax", "coupon", "product_recommendation", "file", "document_template", "notification_template", "journey" ] }, "UniquenessCriteria": { "type": "object", "required": [ "org_id", "resource_type", "fields", "updated_at" ], "properties": { "org_id": { "type": "string" }, "resource_type": { "$ref": "#/components/schemas/UniquenessCriteriaResourceType" }, "fields": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "propagated_to": { "type": "array", "items": { "type": "string" } }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "type": "string" } } }, "LineageEntry": { "type": "object", "properties": { "lineage_id": { "type": "string", "description": "Immutable resource identity across orgs" }, "target_id": { "type": "string", "description": "Resource ID in the destination org" }, "resource_type": { "$ref": "#/components/schemas/ResourceNodeType" }, "blueprint_instance_ids": { "type": "array", "items": { "type": "string" } }, "fidelity": { "type": "string", "enum": [ "full", "partial" ] }, "last_synced_at": { "type": "string", "format": "date-time" } } }, "PatchFieldDiff": { "type": "object", "properties": { "path": { "type": "string" }, "op": { "type": "string", "enum": [ "changed", "added", "removed" ] }, "baseline_value": {}, "current_value": {} } }, "PatchResourceDiff": { "type": "object", "properties": { "type": { "type": "string" }, "source_id": { "type": "string" }, "address": { "type": "string" }, "name": { "type": "string" }, "changes": { "type": "array", "items": { "$ref": "#/components/schemas/PatchFieldDiff" } } } }, "DetectChangesResult": { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/PatchResourceDiff" } } } }, "BlueprintPatch": { "type": "object", "properties": { "patch_id": { "type": "string" }, "version": { "type": "integer" }, "blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "rollout_id": { "type": "string" }, "source_org_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "ready", "applying", "applied", "partial" ] }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/PatchResourceDiff" } }, "changelog": { "type": "string" }, "created_by": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "applied_at": { "type": "string", "format": "date-time" } } }, "OrgPatchExecution": { "type": "object", "properties": { "patch_id": { "type": "string" }, "version": { "type": "integer" }, "org_id": { "type": "string" }, "org_name": { "type": "string" }, "dest_blueprint_id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "success", "failed" ] }, "error": { "type": "string" }, "applied_at": { "type": "string", "format": "date-time" }, "retries": { "type": "integer" }, "changes_applied": { "type": "array", "items": { "$ref": "#/components/schemas/PatchFieldDiff" } } } }, "BlueprintPatchWithResults": { "allOf": [ { "$ref": "#/components/schemas/BlueprintPatch" }, { "type": "object", "properties": { "org_results": { "type": "array", "items": { "$ref": "#/components/schemas/OrgPatchExecution" } } } } ] }, "BlueprintNote": { "type": "object", "description": "A single internal note on a blueprint.", "required": [ "id", "text", "created_at" ], "properties": { "id": { "type": "string", "description": "Server-generated note id.", "example": "3f1c9b0e-2f3a-4a1f-9a3e-6f2b8c7d1e40" }, "text": { "type": "string", "description": "Plain-text note body.", "example": "Adjusted the meter-reading journey for the §14a rollout." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time", "description": "Set the first time the note text is edited." }, "created_by": { "$ref": "#/components/schemas/CallerIdentity" } } }, "BlueprintID": { "type": "string", "description": "ID of a blueprint", "example": "c2d6cac8-bdd5-4ea2-8a6c-1cbdbe77b341" }, "BlueprintResourceID": { "type": "string", "description": "ID of a blueprint resource", "example": "c2d6cac8-bdd5-4ea2-8a6c-1cbdbe77b341" }, "CommonBlueprintFields": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/BlueprintID" }, "title": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "object", "properties": { "preinstall": { "type": "string", "description": "Markdown content shown before starting to install the blueprint", "example": "This is the content of the preinstall.md file which contains the blueprint description.\n" }, "postinstall": { "type": "string", "description": "Markdown content to be displayed when showing the plan to install blueprint", "example": "This is the content of the postinstall.md file\n" } } }, "notes": { "type": "array", "description": "Internal collaboration notes, oldest first. Each entry is stamped with\nits author and creation time server-side; an edit rewrites only `text`\nand stamps `updated_at`, so the history of who noted what stays intact.\nWritten via `addBlueprintNote` / `updateBlueprintNote` /\n`deleteBlueprintNote`, not by `updateBlueprint`.\n\nAvailable on every blueprint including marketplace ones (whose\n`description` is read-only), and never included in the published\nmarketplace package — see `buildMetadata` in\n`services/blueprint-v3/published-blueprint.ts`. Carried to a\ndestination org only when an install/sync passes\n`options.sync_notes: true`.\n", "items": { "$ref": "#/components/schemas/BlueprintNote" } }, "version": { "type": "string" }, "deployments": { "type": "array", "items": { "type": "object", "properties": { "source_org_id": { "type": "string" }, "source_blueprint_id": { "type": "string" }, "destination_org_id": { "type": "string" }, "destination_blueprint_id": { "type": "string" }, "job_id": { "type": "string", "description": "Blueprint installation job that created or updated this deployment record" }, "triggered_at": { "type": "string", "format": "date-time" }, "performed_by": { "allOf": [ { "$ref": "#/components/schemas/CallerIdentity" } ], "description": "Who actually ran this synchronization — the caller of the install job.\nAbsent on deployments recorded before this field existed; consumers\nshould fall back to the blueprint's `updated_by` for those.\n" }, "note": { "type": "string", "description": "User-provided note about this synchronization" }, "status": { "type": "string", "description": "Outcome of this deployment", "enum": [ "IN_PROGRESS", "SUCCESS", "PARTIAL_SUCCESS", "FAILED" ] }, "restore_details": { "type": "object", "description": "Restore lifecycle metadata for this deployment.", "properties": { "has_revertible_changes": { "type": "boolean", "description": "Whether this sync changed destination resources in a way that can\nbe reverted. `false` means the sync completed without create,\nupdate, internal-update, or delete impacts, so there is no revert\naction to offer.\n" }, "resource_impact_summary": { "type": "object", "description": "Counts of resource impact values from the V3 apply result.", "properties": { "create": { "type": "integer", "minimum": 0 }, "update": { "type": "integer", "minimum": 0 }, "internal_update": { "type": "integer", "minimum": 0 }, "delete": { "type": "integer", "minimum": 0 }, "no_op": { "type": "integer", "minimum": 0 }, "ignored": { "type": "integer", "minimum": 0 } } }, "last_restore_job_id": { "type": "string", "description": "BlueprintInstallationJob id of the most recent restore that ran\nagainst this deployment. Used by the FE to keep the restore-status\nbadge visible across page reloads. Frontends poll this job to\nrender the latest restore outcome.\n" }, "last_restore_at": { "type": "string", "format": "date-time", "description": "Timestamp of the most recent restore that ran against this\ndeployment. Stamped when the restore sweep finishes. Used by the\nFE to show when a sync was reverted.\n" }, "last_restored_by": { "type": "object", "description": "Identity of the caller who triggered the most recent restore.\nStamped when the restore sweep finishes. Used by the FE to show\nwho reverted a sync.\n", "properties": { "name": { "type": "string", "description": "Display name (email or token name) of the restorer." }, "user_id": { "type": "string", "description": "User id of the restorer, when triggered by a user." } } }, "status": { "type": "string", "description": "Computed server-side from `(job_id, restore_details.last_restore_job_id, installation_status)`.\n`available` when the deployment is restorable but has no prior\nrestore (including pure-create deployments without `snapshot_id`,\nreverted via sweep-only);\n`in_progress` while an install or restore is running on this\nblueprint instance;\n`restored` / `partially_restored` / `restore_failed` reflect the\nterminal status of the job referenced by `last_restore_job_id`;\n`unavailable` means there is no revert action, for example\nmalformed deployment rows missing `job_id` or no-change syncs.\n", "enum": [ "available", "in_progress", "restored", "partially_restored", "restore_failed", "unavailable" ] } } }, "has_revertible_changes": { "type": "boolean", "deprecated": true, "description": "Deprecated. Use `restore_details.has_revertible_changes`.\n" }, "last_restore_job_id": { "type": "string", "deprecated": true, "description": "Deprecated. Use `restore_details.last_restore_job_id`.\n" }, "restore_status": { "type": "string", "deprecated": true, "description": "Deprecated. Use `restore_details.status`.\n", "enum": [ "available", "in_progress", "restored", "partially_restored", "restore_failed", "unavailable" ] } } } }, "is_verified": { "type": "boolean", "description": "Whether the blueprint is verified by epilot" }, "latest_verification": { "$ref": "#/components/schemas/LatestBlueprintVerification" }, "ignored_resource_addresses": { "type": "array", "description": "Resource addresses excluded during the latest install/update and ignored by verification.", "items": { "type": "string" } }, "installation_status": { "type": "string", "enum": [ "IN_PROGRESS", "CANCELED", "PARTIAL", "SUCCESS", "FAILED" ] }, "active_restore_job_id": { "type": "string", "nullable": true, "description": "ID of the restore (revert) job currently holding a lock on this\nblueprint instance's resources, or null/absent when no revert is\nrunning. Deliberately separate from `installation_status`: installs\nand reverts stay decoupled, so a revert must not overwrite install\nhealth — `installation_status` keeps reflecting the actual install\noutcome (and drives the install badge in the Blueprints overview)\nfor the duration of the revert.\n" }, "active_restore_started_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO timestamp of when the current restore lock\n(`active_restore_job_id`) was acquired, or null/absent when no revert\nis running. Written and cleared alongside `active_restore_job_id`.\nLets the lock self-expire: a lock older than the staleness threshold\n(whose job never completed the sweep, e.g. the state machine was\naborted) is treated as stale so a new revert can proceed instead of\nbeing blocked forever.\n" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/CallerIdentity" }, "updated_by": { "$ref": "#/components/schemas/CallerIdentity" }, "installation_job_ids": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintJobID" } }, "source_blueprint_id": { "description": "ID of the blueprint that brought this blueprint to the destination org (deployed or installed)", "allOf": [ { "$ref": "#/components/schemas/BlueprintID" } ] }, "archived": { "type": "boolean", "description": "Whether the blueprint is archived (soft-deleted). Archived blueprints are hidden from the main list.", "default": false }, "docs_url": { "type": "string", "description": "URL to the blueprint documentation" }, "recommended_apps": { "type": "array", "items": { "type": "string" }, "description": "List of recommended app IDs for the blueprint" }, "required_features": { "type": "object", "description": "Feature constraints for blueprint installation", "properties": { "enabled": { "type": "array", "items": { "type": "string" }, "description": "Features that must be enabled in the target org" }, "disabled": { "type": "array", "items": { "type": "string" }, "description": "Features that must be disabled in the target org" } } }, "zip_file_name": { "type": "string", "description": "Custom name for the exported zip file" } }, "required": [ "title" ] }, "SuggestBlueprintResourcesRequest": { "type": "object", "required": [ "prompt" ], "properties": { "prompt": { "type": "string", "description": "Natural-language description of what to include.", "example": "everything for the hausanschluss use case" }, "blueprint_id": { "allOf": [ { "$ref": "#/components/schemas/BlueprintID" } ], "description": "When provided, suggestions are scoped as additions to this existing\nblueprint — resources already in it are excluded from the response.\n" } } }, "SuggestBlueprintResourcesResponse": { "type": "object", "required": [ "resources" ], "properties": { "resources": { "type": "array", "description": "Suggested resources to add. All marked is_root so the caller can request transitive dependency resolution.", "items": { "$ref": "#/components/schemas/BlueprintResource" } }, "suggested_blueprint_name": { "type": "string", "description": "Short title derived from the prompt. Useful when the caller is\ncreating a new blueprint as a result of the suggestion — saves the\nuser from naming it themselves.\n", "example": "Hausanschluss" }, "explanation": { "type": "string", "description": "Short human-readable summary of what was matched and why." }, "add_dependencies_recommended": { "type": "boolean", "description": "Hint to the caller: persist via bulkAddBlueprintResources with\n?add_dependencies=true so anchor resources (journeys, workflows)\npull their transitive dependencies.\n" } } }, "SkippedBlueprintResource": { "type": "object", "description": "A resource that was requested (or discovered as a dependency) but was not\nadded to the Blueprint. Reasons are stable machine-readable codes.\n", "required": [ "id", "type", "reason" ], "properties": { "id": { "$ref": "#/components/schemas/BlueprintResourceID" }, "type": { "$ref": "#/components/schemas/ResourceNodeType" }, "reason": { "type": "string", "enum": [ "not_found", "source_validation_failed", "enrichment_failed" ] } } }, "BlueprintResource": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/BlueprintResourceID" }, "name": { "type": "string" }, "type": { "$ref": "#/components/schemas/ResourceNodeType" }, "address": { "type": "string" }, "is_root": { "type": "boolean", "description": "When a resource is marked as root, we'll be able to keep track of it's dependencies" }, "is_ready": { "type": "boolean", "description": "when editing a blueprint, this indicates if the resource is ready to be exported and when installing a blueprint, this indicates if the resource is ready to be used" }, "is_hidden": { "type": "boolean", "description": "When a resource is marked as hidden, it's used to hide it from the UI" }, "is_disabled": { "type": "boolean", "default": false, "description": "When a resource is marked as disabled, it will be skipped during export" }, "hard_dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceNodeType" } }, "parent_resource_ids": { "type": "array", "description": "Used to automatically remove resources with hard dependencies and to block deletion of resources with hard dependencies", "items": { "$ref": "#/components/schemas/BlueprintResourceID" } }, "depends_on_addresses": { "type": "array", "description": "Terraform addresses this resource references (for dependency-aware ignore)", "items": { "type": "string" } }, "impact_on_install": { "type": "array", "items": { "type": "string", "enum": [ "create", "update", "internal-update", "no-op", "delete", "ignored", "error" ] } }, "impact_on_install_reason": { "type": "array", "description": "Fields causing the updates / internal updates on a resource install", "items": { "type": "string" } } }, "required": [ "id", "type" ] }, "BlueprintPreview": { "type": "object", "description": "Preview data for a blueprint before installation. Stored temporarily with TTL.", "properties": { "id": { "type": "string", "description": "Unique preview ID" }, "org_id": { "type": "string", "description": "Organization ID" }, "title": { "type": "string" }, "description": { "type": "object", "properties": { "preinstall": { "type": "string" } } }, "version": { "type": "string" }, "slug": { "type": "string" }, "source_type": { "type": "string", "enum": [ "marketplace", "file" ] }, "sync_engine": { "type": "string", "description": "Engine that must install this preview, detected from the uploaded archive's own format (never from a feature flag or request parameter). `v3` is only reported for a correctly shaped and validly signed V3 package. Clients must install a `v3` preview through `POST /v3/blueprint-manifest/blueprint:install` and a `terraform` preview through `POST /v2/blueprint-manifest/blueprints:install`. Absent only on previews created before format detection shipped; treat an absent value as `terraform`.", "enum": [ "terraform", "v3" ] }, "blueprint_file_s3_key": { "type": "string", "description": "S3 key of the blueprint zip file" }, "is_verified": { "type": "boolean" }, "docs_url": { "type": "string" }, "recommended_apps": { "type": "array", "items": { "type": "string" } }, "required_features": { "type": "object", "properties": { "enabled": { "type": "array", "items": { "type": "string" } }, "disabled": { "type": "array", "items": { "type": "string" } } } }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/CallerIdentity" }, "is_updating": { "type": "boolean", "description": "Whether the blueprint is updating to the latest version in the marketplace" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } }, "required": [ "id", "org_id", "title", "source_type", "blueprint_file_s3_key", "is_verified", "created_at", "created_by", "resources", "is_updating" ] }, "CustomBlueprint": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintFields" }, { "type": "object", "properties": { "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } }, "source_type": { "type": "string", "enum": [ "custom" ] } } } ], "required": [ "source_type" ] }, "FileBlueprint": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintFields" }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": [ "file" ] }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } ], "required": [ "source_type" ] }, "MarketplaceBlueprint": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintFields" }, { "type": "object", "properties": { "docs_url": { "type": "string", "description": "URL to the blueprint documentation" }, "source_type": { "type": "string", "enum": [ "marketplace" ] }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } }, "recommended_apps": { "type": "array", "items": { "type": "string" }, "description": "List of recommended app IDs for the blueprint" }, "has_update_available": { "type": "boolean", "description": "Whether a newer version is available in the marketplace." }, "latest_marketplace_version": { "type": "string", "description": "The latest version available in the marketplace.", "example": "v2.0.0" }, "installation_link": { "type": "string", "description": "URL to install/update the blueprint from the marketplace." } } } ], "required": [ "source_type" ] }, "InstalledMarketplaceBlueprintItem": { "type": "object", "description": "Summary of an installed marketplace blueprint for version tracking", "properties": { "id": { "$ref": "#/components/schemas/BlueprintID" }, "slug": { "type": "string", "description": "URL slug of the blueprint from the epilot marketplace", "example": "solar-b2b" }, "version": { "type": "string", "description": "Version of the installed blueprint", "example": "v1.0.0" }, "created_at": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/CallerIdentity" }, "updated_at": { "type": "string", "format": "date-time" }, "updated_by": { "$ref": "#/components/schemas/CallerIdentity" }, "has_update_available": { "type": "boolean", "description": "Whether a newer version is available in the marketplace", "example": true }, "latest_marketplace_version": { "type": "string", "description": "The latest version available in the marketplace", "example": "v2.0.0" }, "installation_link": { "type": "string", "description": "URL to install/update the blueprint from the marketplace" } }, "required": [ "id", "slug" ] }, "DeployedBlueprint": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintFields" }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": [ "deploy" ] }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } ], "required": [ "source_type" ] }, "AppBlueprint": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintFields" }, { "type": "object", "properties": { "source_type": { "type": "string", "enum": [ "app" ] }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintResource" } } } } ], "required": [ "source_type" ] }, "Blueprint": { "oneOf": [ { "$ref": "#/components/schemas/CustomBlueprint" }, { "$ref": "#/components/schemas/FileBlueprint" }, { "$ref": "#/components/schemas/MarketplaceBlueprint" }, { "$ref": "#/components/schemas/DeployedBlueprint" }, { "$ref": "#/components/schemas/AppBlueprint" } ] }, "BlueprintJobID": { "type": "string", "description": "ID of a job", "example": "c2d6cac8-bdd5-4ea2-8a6c-1cbdbe77b341" }, "CommonBlueprintJobFields": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/BlueprintJobID" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintJobEvent" } }, "triggered_at": { "type": "string", "format": "date-time" }, "created_by": { "$ref": "#/components/schemas/CallerIdentity" } } }, "BlueprintExportJob": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintJobFields" }, { "type": "object", "properties": { "job_type": { "type": "string", "enum": [ "export" ] }, "blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "SUCCESS", "FAILED", "CANCELED" ] }, "download_file": { "$ref": "#/components/schemas/S3Reference" } } } ] }, "BlueprintInstallationJob": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintJobFields" }, { "type": "object", "properties": { "job_type": { "type": "string", "enum": [ "install" ] }, "source_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "source_blueprint_type": { "type": "string", "enum": [ "custom", "file", "marketplace", "deploy", "app" ] }, "source_org_id": { "type": "string" }, "source_blueprint_file": { "type": "string" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "destination_org_id": { "type": "string" }, "slug": { "type": "string", "description": "Blueprint slug for marketplace blueprints" }, "sync_engine": { "type": "string", "enum": [ "terraform", "v3" ], "description": "Engine used for this install job" }, "resource_progress": { "type": "array", "description": "Per-resource live status. Populated only for V3 installs.", "items": { "$ref": "#/components/schemas/V3ResourceProgressEntry" } }, "options": { "$ref": "#/components/schemas/BlueprintInstallationJobOptions" }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "WAITING_USER_ACTION", "REAUTH_REQUIRED", "CANCELED", "SUCCESS", "PARTIAL_SUCCESS", "FAILED" ] } } } ] }, "BulkInstallStatus": { "type": "string", "description": "Aggregate status for a bulk install or one of its targets.\n- `QUEUED`: not started yet\n- `IN_PROGRESS`: at least one target queued/in-progress, not all done\n- `SUCCESS`: all targets succeeded\n- `PARTIAL_SUCCESS`: all targets terminal with a mix of success/partial/failure\n- `FAILED`: all targets terminal and none succeeded or partially succeeded\n", "enum": [ "QUEUED", "IN_PROGRESS", "SUCCESS", "PARTIAL_SUCCESS", "FAILED" ] }, "BulkInstallCounts": { "type": "object", "description": "Tally of target rows by status. Recomputed from target rows on each transition.", "properties": { "queued": { "type": "integer" }, "in_progress": { "type": "integer" }, "success": { "type": "integer" }, "partial_success": { "type": "integer" }, "failed": { "type": "integer" } } }, "BulkInstall": { "type": "object", "description": "Bulk install parent. Never carries target auth tokens.", "properties": { "bulk_job_id": { "type": "string" }, "source_org_id": { "type": "string" }, "source_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "status": { "$ref": "#/components/schemas/BulkInstallStatus" }, "target_count": { "type": "integer" }, "max_concurrency": { "type": "integer" }, "counts": { "$ref": "#/components/schemas/BulkInstallCounts" }, "slug": { "type": "string" }, "options": { "$ref": "#/components/schemas/BlueprintInstallationJobOptions" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BulkInstallTarget": { "type": "object", "description": "A single destination of a bulk install. `job` is the hydrated latest child\ninstall job derived from `job_ids.at(-1)`. Auth tokens are never stored or returned.\n", "properties": { "bulk_job_id": { "type": "string" }, "destination_org_id": { "type": "string" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "status": { "$ref": "#/components/schemas/BulkInstallStatus" }, "job_ids": { "type": "array", "items": { "$ref": "#/components/schemas/BlueprintJobID" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "job": { "allOf": [ { "$ref": "#/components/schemas/BlueprintInstallationJob" } ], "nullable": true, "description": "The hydrated latest child install job (`job_ids.at(-1)`), when present." } } }, "BulkInstallTargetList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkInstallTarget" } }, "next_cursor": { "type": "string", "description": "Opaque cursor for the next page. Absent on the last page." } } }, "BulkInstallTargetInput": { "type": "object", "required": [ "destination_org_id", "destination_auth_token" ], "properties": { "destination_org_id": { "type": "string" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "destination_auth_token": { "type": "string", "description": "Write-only org-scoped token for the destination org. Never persisted or returned." } } }, "BulkInstallCreateRequest": { "type": "object", "required": [ "source_blueprint_id", "targets" ], "properties": { "source_org_id": { "type": "string", "description": "The org that owns the source blueprint. Optional; defaults to the caller org and,\nif provided, must equal it — source reads use the caller's token, and the bulk job\nis owned/polled by the caller org. A different value is rejected with 400.\n" }, "source_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "max_concurrency": { "type": "integer", "minimum": 1, "maximum": 5, "default": 2, "description": "Maximum number of concurrently active child installs." }, "slug": { "type": "string" }, "options": { "$ref": "#/components/schemas/BlueprintInstallationJobOptions" }, "targets": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/BulkInstallTargetInput" } } } }, "BlueprintRestoreJob": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintJobFields" }, { "type": "object", "properties": { "job_type": { "type": "string", "enum": [ "restore" ] }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "destination_org_id": { "type": "string" }, "install_job_id": { "type": "string", "nullable": true, "description": "The install job whose deployment is being reverted. Maps back\nto the entry in `Blueprint.deployments[]`.\n" }, "snapshot_id": { "type": "string", "nullable": true, "description": "The snapshot driving Phase 1 of the restore. Null for sweep-only\nrestores (pure-create deployments with no captured manifest).\n" }, "sync_engine": { "type": "string", "enum": [ "v3" ] }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "SUCCESS", "PARTIAL_SUCCESS", "FAILED" ] }, "restore_result": { "nullable": true, "description": "Absent while the job is still IN_PROGRESS.", "allOf": [ { "$ref": "#/components/schemas/RestoreOutcome" } ] } } } ] }, "V3ResourceProgressEntry": { "type": "object", "required": [ "lineage_id", "type", "address", "status" ], "properties": { "lineage_id": { "type": "string" }, "type": { "type": "string" }, "address": { "type": "string" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "in_progress", "done", "failed", "skipped" ] }, "target_id": { "type": "string" }, "error_message": { "type": "string" }, "error_code": { "type": "string", "description": "Stable machine code for a failed resource, when config-engine threw a\ntyped error. Keys a translation in the Blueprints UI; `error_message`\nis the English fallback when absent or unrecognised.\n" }, "error_data": { "type": "object", "additionalProperties": true, "description": "Interpolation values for the translated `error_code` message." } } }, "RestoreOutcomeItem": { "type": "object", "required": [ "lineage_id", "type", "action" ], "properties": { "lineage_id": { "type": "string" }, "type": { "type": "string" }, "name": { "type": "string", "nullable": true }, "target_id": { "type": "string", "nullable": true }, "action": { "type": "string", "description": "On `restore-preview`: the action the restore would take.\nOn `restore_result`: the action that was applied.\n`failed` only appears on `restore_result`.\n", "enum": [ "restore", "delete", "skip", "failed" ] }, "reason": { "type": "string", "nullable": true, "description": "Only set when `action == skip`.", "enum": [ "modified", "delete_unsupported", "heuristic_match", "co_owned", "dependency_protected", "already_deleted", "non_revertible" ] }, "last_synced_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Only set when `reason == modified`. From the lineage row's last install write." }, "current_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Only set when `reason == modified`. From the destination resource's current state." }, "error_message": { "type": "string", "nullable": true, "description": "Only set when `action == failed`." }, "is_hidden": { "type": "boolean", "description": "Mirrors the install manifest's `is_hidden` for this resource —\nhelper resources (entity mappings, datasources, flow-template\nautomations) the UI hides on every other resources view. Absent\non rows from legacy installs without a persisted manifest.\n" }, "co_owned_by": { "type": "array", "description": "Only set when `reason == co_owned`. The other live blueprint\ninstances that still own this resource's lineage row — the\n\"another sync\" the skip refers to.\n", "items": { "type": "object", "required": [ "blueprint_id" ], "properties": { "blueprint_id": { "type": "string" }, "title": { "type": "string", "nullable": true } } } }, "protected_by": { "type": "array", "description": "Only set when `reason == dependency_protected`. The surviving\nresource(s) whose 'hard' reference to this one is why it wasn't\ndeleted (e.g. a skipped Journey still triggering this Automation).\n", "items": { "type": "object", "required": [ "lineage_id", "type" ], "properties": { "lineage_id": { "type": "string" }, "type": { "type": "string" }, "target_id": { "type": "string", "nullable": true } } } } } }, "HealthFinding": { "type": "object", "required": [ "check_id", "code", "severity", "resource_type", "lineage_id", "message" ], "properties": { "check_id": { "type": "string", "enum": [ "live_readability", "referential_integrity", "install_completeness", "schema_consistency", "mapping_integrity", "execution_readiness", "catalog_hygiene", "spec_conformance" ] }, "code": { "type": "string", "enum": [ "missing_in_destination", "fetch_error", "no_readback", "unreplaced_source_reference", "broken_internal_reference", "dropped_at_install", "orphaned_group_reference", "uuid_group_label", "unreachable_attribute_purpose", "duplicate_attribute_name", "duplicate_headline", "broken_mapping_reference", "stale_mapping_version", "mapping_slot_mismatch", "mapping_parity_mismatch", "stale_lineage", "broken_trigger_reference", "broken_action_reference", "broken_workflow_step", "invalid_mapping_target", "invalid_mapping_source", "invalid_mapping_version", "unknown_mapping_attribute", "workflow_edge_limit", "dead_purpose_reference", "broken_portal_reference", "orphaned_portal_block", "broken_closing_reason", "broken_journey_settings", "unresolved_assignee", "current_write_invalid", "duplicate_live_resource", "missing_file_content", "file_etag_mismatch", "incomplete_webhook", "broken_template_reference", "orphaned_price", "duplicate_price", "inactive_price_in_use", "cross_org_reference" ] }, "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "resource_type": { "type": "string" }, "lineage_id": { "type": "string" }, "target_id": { "type": "string" }, "resource_name": { "type": "string", "description": "Human-readable name of the affected resource" }, "message": { "type": "string" }, "verdict": { "type": "string", "description": "Mechanical root-cause classification and suggested fix, when determinable" }, "evidence": { "type": "object", "description": "Check-specific evidence, e.g. the JSON path and referenced id of a broken reference.", "properties": { "path": { "type": "string" }, "referenced_id": { "type": "string" }, "referenced_type": { "type": "string" }, "referenced_name": { "type": "string", "description": "Human-readable name or logical slug of the referenced source resource" }, "referenced_lineage_id": { "type": "string", "description": "Logical source lineage identity of the referenced resource" }, "expected_target_id": { "type": "string", "description": "Destination id that should have replaced the source reference" }, "reference_kind": { "type": "string", "description": "Human-readable description of the exact field carrying the reference" }, "operation": { "type": "string" }, "rejection_reason": { "type": "string" }, "error_message": { "type": "string" }, "response_status": { "type": "integer" } } } } }, "HealthCheckCoverage": { "type": "object", "required": [ "check_id", "status", "scope", "resources_considered", "details" ], "properties": { "check_id": { "type": "string", "enum": [ "live_readability", "referential_integrity", "install_completeness", "schema_consistency", "mapping_integrity", "execution_readiness", "spec_conformance" ] }, "status": { "type": "string", "enum": [ "completed", "partial", "skipped", "not_applicable" ] }, "scope": { "type": "string", "enum": [ "tracked_resources", "org_wide", "source_comparison" ] }, "resources_considered": { "type": "integer" }, "details": { "type": "array", "items": { "type": "string" } } } }, "HealthResourceTypeCoverage": { "type": "object", "required": [ "resource_type", "tracked", "readable_by_lineage", "missing_by_lineage", "read_errors", "unchecked", "specialized_checks", "known_blind_spots" ], "properties": { "resource_type": { "type": "string" }, "tracked": { "type": "integer" }, "readable_by_lineage": { "type": "integer" }, "missing_by_lineage": { "type": "integer" }, "read_errors": { "type": "integer" }, "unchecked": { "type": "integer" }, "specialized_checks": { "type": "array", "items": { "type": "string", "enum": [ "live_readability", "referential_integrity", "install_completeness", "schema_consistency", "mapping_integrity", "execution_readiness", "spec_conformance" ] } }, "known_blind_spots": { "type": "array", "description": "Type-specific contracts the current scanner explicitly does not claim to validate.", "items": { "type": "string" } } } }, "HealthScanCoverage": { "type": "object", "required": [ "checks", "resource_types" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/HealthCheckCoverage" } }, "resource_types": { "type": "array", "items": { "$ref": "#/components/schemas/HealthResourceTypeCoverage" } } } }, "DeploymentHealthReport": { "type": "object", "required": [ "status", "job_id", "blueprint_instance_id", "destination_org_id", "generated_at" ], "properties": { "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "job_id": { "$ref": "#/components/schemas/BlueprintJobID" }, "blueprint_instance_id": { "$ref": "#/components/schemas/BlueprintID" }, "destination_org_id": { "type": "string" }, "generated_at": { "type": "string", "format": "date-time" }, "html_url": { "type": "string", "description": "Presigned link to the rendered HTML report (present once the check completed)" }, "summary": { "type": "object", "properties": { "resources_scanned": { "type": "integer" }, "unchecked": { "type": "integer" }, "errors": { "type": "integer" }, "warnings": { "type": "integer" }, "infos": { "type": "integer" } } }, "findings": { "type": "array", "items": { "$ref": "#/components/schemas/HealthFinding" } }, "coverage": { "$ref": "#/components/schemas/HealthScanCoverage" }, "error": { "type": "string", "description": "Failure reason when status is `failed`." } } }, "RestoreOutcome": { "type": "object", "properties": { "snapshot_id": { "type": "string", "nullable": true, "description": "The snapshot driving Phase 1 of the restore. Null/absent for\nsweep-only restores (pure-create deployments with no captured\nmanifest).\n" }, "resources": { "type": "array", "items": { "$ref": "#/components/schemas/RestoreOutcomeItem" } }, "has_effective_changes": { "type": "boolean", "description": "`true` iff at least one entry in `resources` has an effective\naction (`action` is `restore` or `delete`). `false` when every\nresource would be skipped (all `skip` / `failed`). Consumers\ncan gate the \"Revert sync\" confirm button on this — if false,\nexecuting the revert is a no-op.\n" } } }, "BlueprintJob": { "oneOf": [ { "$ref": "#/components/schemas/BlueprintExportJob" }, { "$ref": "#/components/schemas/BlueprintInstallationJob" }, { "$ref": "#/components/schemas/BlueprintRestoreJob" }, { "$ref": "#/components/schemas/BlueprintDependenciesSyncJob" }, { "$ref": "#/components/schemas/BlueprintValidateJob" }, { "$ref": "#/components/schemas/BlueprintVerificationJob" } ], "discriminator": { "propertyName": "job_type", "mapping": { "export": "#/components/schemas/BlueprintExportJob", "install": "#/components/schemas/BlueprintInstallationJob", "restore": "#/components/schemas/BlueprintRestoreJob", "dependencies_sync": "#/components/schemas/BlueprintDependenciesSyncJob", "validate": "#/components/schemas/BlueprintValidateJob", "verification": "#/components/schemas/BlueprintVerificationJob" } } }, "BlueprintDependenciesSyncJob": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintJobFields" }, { "type": "object", "properties": { "job_type": { "type": "string", "enum": [ "dependencies_sync" ] }, "blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "SUCCESS", "FAILED", "CANCELED" ] } } } ] }, "BlueprintValidateJob": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintJobFields" }, { "type": "object", "properties": { "job_type": { "type": "string", "enum": [ "validate" ] }, "blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "SUCCESS", "FAILED" ] }, "valid": { "type": "boolean", "description": "Present when status is SUCCESS or FAILED." }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FormattedError" }, "description": "Present when valid is false." } } } ] }, "BlueprintVerificationJob": { "allOf": [ { "$ref": "#/components/schemas/CommonBlueprintJobFields" }, { "type": "object", "properties": { "job_type": { "type": "string", "enum": [ "verification" ] }, "source_org_id": { "type": "string" }, "source_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "destination_org_id": { "type": "string" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "installation_job_id": { "allOf": [ { "$ref": "#/components/schemas/BlueprintJobID" } ], "description": "Install job this verification is checking, when known." }, "sync_engine": { "type": "string", "enum": [ "terraform", "v3" ], "description": "Install engine used by the linked installation job, when known." }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "SUCCESS", "PARTIAL_SUCCESS", "FAILED" ] }, "summary": { "$ref": "#/components/schemas/VerificationSummary" }, "resource_results": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceVerificationResult" } }, "resource_results_s3_key": { "type": "string", "description": "S3 key for detailed results when too large for inline storage." } } } ] }, "LatestBlueprintVerification": { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/BlueprintJobID" }, "status": { "type": "string", "enum": [ "IN_PROGRESS", "SUCCESS", "PARTIAL_SUCCESS", "FAILED" ] }, "triggered_at": { "type": "string", "format": "date-time" }, "source_org_id": { "type": "string" }, "source_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "destination_org_id": { "type": "string" }, "destination_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "installation_job_id": { "$ref": "#/components/schemas/BlueprintJobID" }, "sync_engine": { "type": "string", "enum": [ "terraform", "v3" ] }, "summary": { "$ref": "#/components/schemas/VerificationSummary" } } }, "VerificationSummary": { "type": "object", "properties": { "total_resources": { "type": "integer" }, "matched": { "type": "integer" }, "mismatched": { "type": "integer" }, "missing_in_destination": { "type": "integer" }, "fetch_errors": { "type": "integer" } } }, "ResourceVerificationResult": { "type": "object", "properties": { "resource_type": { "$ref": "#/components/schemas/ResourceNodeType" }, "resource_name": { "type": "string" }, "source_resource_id": { "type": "string" }, "source_resource_address": { "type": "string" }, "destination_resource_id": { "type": "string" }, "destination_resource_address": { "type": "string" }, "status": { "type": "string", "enum": [ "matched", "mismatched", "missing_in_destination", "fetch_error" ] }, "failure_context": { "type": "string", "enum": [ "depends_on_failed_resource", "may_be_caused_by_failed_dependency" ], "description": "Explains whether this result is likely downstream of another failed resource." }, "failed_dependency_resource_ids": { "type": "array", "items": { "type": "string" } }, "failed_dependency_resource_names": { "type": "array", "items": { "type": "string" } }, "failed_dependency_addresses": { "type": "array", "items": { "type": "string" } }, "field_diffs": { "type": "array", "items": { "$ref": "#/components/schemas/FieldDiff" } }, "error": { "type": "string" } } }, "FieldDiff": { "type": "object", "properties": { "path": { "type": "string", "description": "JSON path to the differing field (e.g. \"steps[2].name\")" }, "source_value": {}, "destination_value": {}, "diff_type": { "type": "string", "enum": [ "value_changed", "field_missing_in_destination", "field_missing_in_source", "type_mismatch" ] } } }, "BlueprintJobEvent": { "type": "object", "properties": { "timestamp": { "type": "string", "format": "date-time" }, "message": { "type": "string" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FormattedError" } }, "level": { "type": "string", "enum": [ "info", "warning", "error" ] }, "data": { "type": "object", "properties": { "installed_blueprint_id": { "$ref": "#/components/schemas/BlueprintID" }, "export_job_id": { "$ref": "#/components/schemas/BlueprintJobID" }, "resources": { "type": "number" } } } } }, "BlueprintInstallationJobOptions": { "type": "object", "properties": { "resources_to_ignore": { "description": "List of resource addresses to ignore changes for. When a resource is marked as create, it will be ignored and not created.", "type": "array", "items": { "type": "string" } }, "sync_notes": { "description": "When `true`, the source blueprint's `notes` overwrite the destination\nblueprint's `notes`. Defaults to `false`, which leaves the\ndestination's notes untouched.\n", "type": "boolean", "default": false } } }, "ContinueInstallationJobRequest": { "allOf": [ { "$ref": "#/components/schemas/BlueprintInstallationJobOptions" }, { "type": "object", "properties": { "source_auth_token": { "description": "A freshly issued bearer for the SOURCE organization, used only when resuming a\njob paused at `REAUTH_REQUIRED` whose source credential also expired. Applies to\ncross-org installs: apply-time reads such as the authenticated File API fallback\nfor private source files run against the source org, so the destination bearer\ncannot stand in for them. Omit it to keep the source token the job already has.\n", "type": "string", "format": "password" } } } ] }, "ManifestID": { "type": "string", "description": "ID of an imported / installed manifest", "example": "c2d6cac8-bdd5-4ea2-8a6c-1cbdbe77b341" }, "JobID": { "type": "string", "description": "ID of an import or export job (state machine)", "example": "4854bb2a-94f9-424d-a968-3fb17fb0bf89" }, "ManifestSource": { "type": "string", "enum": [ "file", "marketplace", "sandbox" ] }, "Manifest": { "allOf": [ { "type": "object", "properties": { "import_job_id": { "$ref": "#/components/schemas/JobID" }, "previous_jobs_ids": { "type": "array", "items": { "type": "string" }, "description": "List of job IDs that were used to install the manifest" }, "previous_jobs": { "type": "array", "items": { "$ref": "#/components/schemas/Job" }, "description": "List of jobs that were used to install the manifest" } } }, { "$ref": "#/components/schemas/CommonManifestFields" }, { "$ref": "#/components/schemas/CommonMarkdownFields" }, { "$ref": "#/components/schemas/CommonImportFields" }, { "$ref": "#/components/schemas/ManifestTimestampFields" } ] }, "ManifestItem": { "allOf": [ { "$ref": "#/components/schemas/CommonManifestFields" }, { "$ref": "#/components/schemas/ManifestTimestampFields" } ] }, "JobStatus": { "type": "string", "enum": [ "PENDING", "STARTED", "WAITING_USER_ACTION", "REAUTH_REQUIRED", "CANCELED", "IN_PROGRESS", "SUCCESS", "PARTIAL_SUCCESS", "FAILED" ] }, "ResourceNodeType": { "type": "string", "description": "Type of the resource", "enum": [ "designbuilder", "journey", "product", "price", "product_recommendation", "coupon", "tax", "automation_flow", "entity_mapping", "file", "emailtemplate", "schema", "schema_attribute", "schema_capability", "schema_group", "schema_group_headline", "workflow_definition", "closing_reason", "taxonomy_classification", "webhook", "integration", "dashboard", "insight", "custom_variable", "usergroup", "saved_view", "app", "role", "portal_config", "target", "kanban", "validation_rule", "flow_template", "taxonomy", "notification_template", "environment_variable", "datasource", "family", "permission" ] }, "PlanChanges": { "type": "array", "items": { "type": "string", "enum": [ "create", "update", "internal-update", "no-op", "delete", "ignored" ] } }, "CommonResourceNode": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the resource" }, "type": { "$ref": "#/components/schemas/ResourceNodeType" }, "name": { "type": "string", "description": "Name of the resource" }, "source_id": { "type": "string", "description": "Source ID of the resource" }, "is_virtual": { "type": "boolean", "description": "Whether the resource is virtual" } }, "required": [ "id", "type" ] }, "RootResourceNode": { "allOf": [ { "$ref": "#/components/schemas/CommonResourceNode" }, { "type": "object", "properties": { "address": { "type": "string", "description": "Terraform address of the resource" }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/VirtualResourceNodeGroup" }, "description": "Dependencies of the resource", "nullable": true }, "changes": { "$ref": "#/components/schemas/PlanChanges" }, "changes_reason": { "type": "array", "description": "Fields causing the updates / internal updates on a resource install", "items": { "type": "string" } } } } ] }, "VirtualResourceNodeGroup": { "allOf": [ { "$ref": "#/components/schemas/CommonResourceNode" }, { "type": "object", "properties": { "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceNode" } }, "is_virtual": { "type": "boolean", "enum": [ true ] } } } ] }, "ResourceNode": { "allOf": [ { "$ref": "#/components/schemas/CommonResourceNode" }, { "type": "object", "properties": { "address": { "type": "string", "description": "Terraform address of the resource" }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceNode" }, "description": "Dependencies of the resource", "nullable": true }, "parents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/ResourceNodeType" } } } }, "source_id": { "description": "Original ID of the exported resource", "type": "string" }, "changes": { "$ref": "#/components/schemas/PlanChanges" }, "changes_reason": { "type": "array", "description": "Fields causing the updates / internal updates on a resource install", "items": { "type": "string" } } } } ] }, "Job": { "allOf": [ { "type": "object", "properties": { "job_id": { "$ref": "#/components/schemas/JobID" }, "job_status": { "$ref": "#/components/schemas/JobStatus" }, "manifest_file_path": { "type": "string", "description": "The S3 key of the manifest file" }, "message": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "plan_file_content": { "type": "string", "description": "An URL to download the plan file" }, "resources_to_export": { "description": "An array of tree-like JSON objects or a singular tree-like JSON object representing the resources to import", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/RootResourceNode" } }, { "$ref": "#/components/schemas/RootResourceNode" } ] }, "large_resources_to_export_url": { "type": "string", "description": "An URL to download the resources to export when the resources are too large to be included in the response" }, "resources_to_import": { "description": "An array of tree-like JSON objects or a singular tree-like JSON object representing the resources to import", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/RootResourceNode" } }, { "$ref": "#/components/schemas/RootResourceNode" } ] }, "large_resources_to_import_url": { "type": "string", "description": "An URL to download the resources to import when the resources are too large to be included in the response" }, "resource_replacements": { "type": "array", "items": { "$ref": "#/components/schemas/ResourceReplacement" } }, "is_verified": { "type": "boolean", "description": "Whether the manifest comes from a trusted source and is signed by epilot" }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/FormattedError" } } } }, { "$ref": "#/components/schemas/CommonImportFields" }, { "$ref": "#/components/schemas/CommonMarkdownFields" }, { "$ref": "#/components/schemas/CommonManifestFields" } ] }, "UploadFilePayload": { "type": "object", "properties": { "filename": { "type": "string", "example": "example.manifest.zip" } }, "required": [ "filename" ] }, "S3Reference": { "type": "object", "properties": { "bucket": { "type": "string", "example": "blueprint-manifest-prod-blueprintsv2bucket-sybpsryropzw" }, "key": { "type": "string", "example": "templates/main.tf" } }, "required": [ "bucket", "key" ] }, "CommonManifestFields": { "type": "object", "properties": { "manifest_id": { "$ref": "#/components/schemas/ManifestID" }, "source_type": { "$ref": "#/components/schemas/ManifestSource" }, "source_blueprint_name": { "type": "string", "example": "Solar B2B" }, "source_blueprint_slug": { "type": "string", "description": "URL slug of a blueprint from the epilot marketplace", "example": "solar-b2b" }, "source_blueprint_version": { "type": "string", "description": "Version of the blueprint (semver)", "example": "1.0.0" }, "pre_install_requirements": { "$ref": "#/components/schemas/PreInstallRequirements" }, "source_blueprint_file": { "type": "string", "deprecated": true, "description": "A URL to download the source blueprint file used to import the blueprint", "example": "https://blueprint-manifest-prod.s3.eu-central-1.amazonaws.com/manifest.zip" }, "docs_link": { "type": "string", "description": "Link to the blueprint documentation", "example": "https://help.epilot.cloud" }, "source_blueprint_file_ref": { "$ref": "#/components/schemas/S3Reference" }, "install_status": { "$ref": "#/components/schemas/BlueprintInstallStatus" }, "install_status_description": { "type": "string", "example": "This blueprint installation resulted in a partial deployment; some resources were created successfully, but failed to complete the full resource setup." }, "is_verified": { "type": "boolean", "description": "Whether the manifest comes from a trusted source and is signed by epilot" }, "created_by": { "$ref": "#/components/schemas/CallerIdentity" }, "updated_by": { "$ref": "#/components/schemas/CallerIdentity" }, "manifest_version": { "type": "string", "description": "Version of the manifest (semver)", "example": "1.0.0" }, "selected_resources_url": { "type": "string", "description": "All the resources that were selected to be exported, used to pre-select the resources when updating a sandbox manifest", "example": "https://blueprint-manifest-prod.s3.eu-central-1.amazonaws.com/selected_resources.json" }, "ready_imported_resources_url": { "type": "string", "description": "All the resources that were marked as ready by the user", "example": "https://blueprint-manifest-prod.s3.eu-central-1.amazonaws.com/ready_imported_resources.json" }, "deployed_from": { "type": "object", "properties": { "source_organization_id": { "type": "string", "description": "ID of the organization that deployed the manifest" }, "source_manifest_id": { "type": "string", "description": "ID of the manifest that was deployed" }, "source_organization_type": { "type": "string", "enum": [ "sandbox", "production" ] }, "last_triggered_at": { "type": "string", "format": "date-time", "description": "When the deployment was last triggered" } }, "description": "Information about the manifest that was deployed from, used to update existing deployments instead of always creating new ones" }, "deployed_to": { "type": "array", "items": { "type": "object", "properties": { "destination_organization_id": { "type": "string", "description": "ID of the organization that the manifest was deployed to" }, "destination_manifest_id": { "type": "string", "description": "ID of the manifest that was deployed to" }, "destination_organization_type": { "type": "string", "enum": [ "sandbox", "production" ] }, "last_triggered_at": { "type": "string", "format": "date-time", "description": "When the deployment was last triggered" } } }, "description": "Information about the manifest that was deployed to, used to update existing deployments instead of always creating new ones" } } }, "ManifestTimestampFields": { "type": "object", "properties": { "created_at": { "description": "When the manifest was first installed (applied)", "type": "string", "format": "date-time" }, "updated_at": { "description": "When the manifest was last updated (applied)", "type": "string", "format": "date-time" } } }, "CommonImportFields": { "type": "object", "properties": { "source_type": { "$ref": "#/components/schemas/ManifestSource" }, "imported_resources": { "description": "An array of tree-like JSON objects or a singular tree-like JSON object representing the resources to import", "oneOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/RootResourceNode" } }, { "$ref": "#/components/schemas/RootResourceNode" } ] }, "large_imported_resources_url": { "type": "string", "format": "uri", "description": "An URL to download the imported resources when the resources are too large to be included in the response", "example": "https://blueprint-manifest-prod.s3.eu-central-1.amazonaws.com/large.json" } } }, "CommonMarkdownFields": { "type": "object", "properties": { "markdown": { "type": "object", "description": "Markdown content part of a manifest file", "properties": { "manifest": { "type": "string", "description": "Markdown content shown before installing the manifest", "example": "This is the content of the manifest.md file which contains the manifest descripton.\n" }, "preinstall": { "type": "string", "deprecated": true, "description": "Markdown content to be displayed when showing the plan to install blueprint", "example": "This is the content of the preinstall.md file\n" }, "postinstall": { "type": "string", "description": "Markdown content to be displayed when showing the plan to install blueprint", "example": "This is the content of the postinstall.md file\n" } } } } }, "PreInstallRequirements": { "type": "array", "items": { "type": "string" }, "description": "List of feature settings that must be enabled before installing the blueprint", "example": [ "journey_automation", "ticket-entities", "advanced_permissions" ] }, "BlueprintInstallStatus": { "type": "string", "enum": [ "SUCCESS", "PARTIAL", "FAILED" ] }, "FormattedErrorCodes": { "type": "string", "enum": [ "dependency_extraction", "resource_not_found", "resource_fetch_api_error", "resource_fetch_unknown_error", "terraform_cli_process_error", "terraform_import_block_process_error", "terraform_init_error", "terraform_validate_error", "terraform_plan_error", "terraform_apply_error", "terraform_show_error", "generic_error", "bad_request", "forbidden", "conflict", "not_found", "undeclared_resource", "invalid_readonly_attribute", "invalid_attribute_value", "unsupported_attribute", "self_referential_block", "circular_dependency", "state_mismatch", "import_nonexistent_object", "provider_install_error", "stale_blueprint" ] }, "FormattedErrorData": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" } } }, "FormattedError": { "type": "object", "properties": { "error": { "anyOf": [ { "type": "string" }, { "type": "object" } ] }, "code": { "$ref": "#/components/schemas/FormattedErrorCodes" }, "data": { "type": "object", "properties": { "formattedResource": { "$ref": "#/components/schemas/FormattedErrorData" }, "resource": { "type": "string" }, "resourceDependency": { "type": "string" }, "resources": { "type": "array", "items": { "type": "string" } }, "addresses": { "type": "array", "items": { "type": "string" } }, "originalError": { "type": "string" } } } } }, "CallerIdentity": { "type": "object", "properties": { "name": { "description": "a human readable name of the caller (e.g. user name, token name or email address)", "example": "manifest@epilot.cloud" }, "org_id": { "description": "epilot organization id", "type": "string", "example": "911690" }, "user_id": { "description": "epilot user id, when called by a user", "type": "string", "example": "11001045" }, "token_id": { "description": "token id, when called by API token", "type": "string", "example": "api_5ZugdRXasLfWBypHi93Fk" } }, "required": [ "org_id" ] }, "SelectedResources": { "type": "object", "properties": { "exported_root_resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "$ref": "#/components/schemas/ResourceNodeType" }, "address": { "type": "string", "description": "Terraform address of the resource" } }, "required": [ "id", "type" ] } }, "selected_resources": { "type": "array", "items": { "type": "string" } }, "pipeline_id": { "type": "string", "description": "Pipeline ID selected when doing the sandbox sync" } }, "required": [ "exported_root_resources", "selected_resources" ] }, "ResourceReplacement": { "type": "object", "properties": { "originalAddress": { "type": "string", "description": "Original resource ID to be replaced" }, "replacementId": { "type": "string", "description": "ID of the resource that will replace the original" }, "replacementName": { "type": "string", "description": "Name of the resource that will replace the original" } }, "required": [ "originalAddress", "replacementId" ] }, "PutManifestPayload": { "type": "object", "properties": { "source_blueprint_name": { "type": "string", "description": "Name of the source blueprint" }, "markdown": { "type": "string", "description": "Markdown content of the manifest" }, "ready_resources": { "type": "array", "items": { "type": "string" }, "description": "Array of ids of resources selected to be ready by the user" }, "deployed_to": { "type": "array", "items": { "type": "object", "properties": { "destination_organization_id": { "type": "string", "description": "ID of the organization that the manifest was deployed to" }, "destination_manifest_id": { "type": "string", "description": "ID of the manifest that was deployed to" }, "destination_organization_type": { "type": "string", "enum": [ "sandbox", "production" ] }, "last_triggered_at": { "type": "string" } } } } } }, "MarketplaceListing": { "type": "object", "required": [ "id", "blueprint_id", "name", "slug", "status" ], "properties": { "id": { "type": "string", "format": "uuid" }, "blueprint_id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "documentation_url": { "type": "string", "nullable": true }, "pricing_type": { "type": "string", "enum": [ "free", "paid", "freemium", "contact_us" ], "nullable": true }, "support_email": { "type": "string", "nullable": true }, "portal_description": { "type": "string", "nullable": true }, "teaser_name": { "type": "string", "nullable": true }, "teaser_short_description": { "type": "string", "nullable": true }, "teaser_thumbnail": { "type": "string", "nullable": true }, "details_page_title": { "type": "string", "nullable": true }, "details_page_description": { "type": "string", "nullable": true }, "details_page_hero_image": { "type": "string", "nullable": true }, "details_page_carousel": { "type": "array", "items": { "type": "string" }, "nullable": true }, "resources_section_description": { "type": "string", "nullable": true }, "resources_section_benefits_title": { "type": "string", "nullable": true }, "resources_section_benefits_list": { "type": "string", "nullable": true }, "resources_section_process_details": { "type": "string", "nullable": true }, "partner": { "type": "string", "nullable": true }, "partner_subtext": { "type": "string", "nullable": true }, "partner_logo": { "type": "string", "nullable": true }, "partner_website_link": { "type": "string", "nullable": true }, "last_updated_on": { "type": "string", "nullable": true }, "requires_customer_portal": { "type": "boolean", "nullable": true }, "process_details_section_title": { "type": "string", "nullable": true }, "is_new_blueprint": { "type": "boolean", "nullable": true }, "available_in": { "type": "string", "nullable": true }, "testimonials": { "type": "array", "items": { "type": "string" }, "nullable": true }, "installation_link": { "type": "string", "nullable": true }, "installation_slug": { "type": "string", "nullable": true }, "demo_form_link": { "type": "string", "nullable": true }, "order": { "type": "number", "nullable": true }, "categories": { "type": "array", "items": { "type": "string" }, "nullable": true }, "main_category": { "type": "array", "items": { "type": "string" }, "nullable": true }, "status": { "type": "string", "enum": [ "draft", "live", "archived" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MarketplaceListingUpdate": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "logo": { "type": "string", "nullable": true }, "documentation_url": { "type": "string", "nullable": true }, "pricing_type": { "type": "string", "enum": [ "free", "paid", "freemium", "contact_us" ], "nullable": true }, "support_email": { "type": "string", "nullable": true }, "portal_description": { "type": "string", "nullable": true }, "teaser_name": { "type": "string", "nullable": true }, "teaser_short_description": { "type": "string", "nullable": true }, "teaser_thumbnail": { "type": "string", "nullable": true }, "details_page_title": { "type": "string", "nullable": true }, "details_page_description": { "type": "string", "nullable": true }, "details_page_hero_image": { "type": "string", "nullable": true }, "details_page_carousel": { "type": "array", "items": { "type": "string" }, "nullable": true }, "resources_section_description": { "type": "string", "nullable": true }, "resources_section_benefits_title": { "type": "string", "nullable": true }, "resources_section_benefits_list": { "type": "string", "nullable": true }, "resources_section_process_details": { "type": "string", "nullable": true }, "partner": { "type": "string", "nullable": true }, "partner_subtext": { "type": "string", "nullable": true }, "partner_logo": { "type": "string", "nullable": true }, "partner_website_link": { "type": "string", "nullable": true }, "last_updated_on": { "type": "string", "nullable": true }, "requires_customer_portal": { "type": "boolean", "nullable": true }, "process_details_section_title": { "type": "string", "nullable": true }, "is_new_blueprint": { "type": "boolean", "nullable": true }, "available_in": { "type": "string", "nullable": true }, "testimonials": { "type": "array", "items": { "type": "string" }, "nullable": true }, "installation_link": { "type": "string", "nullable": true }, "installation_slug": { "type": "string", "nullable": true }, "demo_form_link": { "type": "string", "nullable": true }, "order": { "type": "number", "nullable": true }, "categories": { "type": "array", "items": { "type": "string" }, "nullable": true }, "main_category": { "type": "array", "items": { "type": "string" }, "nullable": true } } }, "MarketplaceListingVersion": { "type": "object", "required": [ "id", "listing_id", "status", "draft_label", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "listing_id": { "type": "string" }, "status": { "type": "string", "enum": [ "draft", "published", "archived" ] }, "version_name": { "type": "string", "nullable": true }, "draft_label": { "type": "string" }, "update_note": { "type": "string", "nullable": true }, "resources": { "type": "array", "items": { "type": "object" }, "nullable": true }, "required_features": { "type": "array", "items": { "type": "string" }, "nullable": true }, "recommended_apps": { "type": "array", "items": { "type": "string" }, "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "published_at": { "type": "string", "format": "date-time", "nullable": true } } } }, "parameters": { "JobID": { "name": "job_id", "in": "path", "required": true, "description": "ID of an import or export job", "schema": { "$ref": "#/components/schemas/JobID" } } }, "securitySchemes": { "EpilotAuth": { "type": "http", "scheme": "bearer", "description": "Authorization header with epilot OAuth2 bearer token", "bearerFormat": "JWT" } } } }