{
  "openapi": "3.1.0",
  "info": {
    "title": "Jetstack AI — Core API",
    "version": "1.0.0",
    "description": "Machine-to-machine access to your organization's portals, HubSpot assets, asset library, modules, tasks and audits. The same API powers the Jetstack CLI and MCP server.\n\n## Authentication\n\nSend your API key as a bearer token:\n\n```\nAuthorization: Bearer jsai_your_api_key\n```\n\nCreate keys in the app under **Settings → Access Tokens**. Each key carries scopes, and every endpoint lists the scope it needs.\n\nIf your organization runs on a dedicated Jetstack instance, also send its Instance ID (shown under **Connection Details** on the same page). Everyone else can leave it out.\n\n```\nX-Instance-Id: your-instance-id\n```\n\n```bash\ncurl https://api.jetstack.ai/v1/health \\\n  -H \"Authorization: Bearer jsai_...\"\n```\n\n## Rate limits\n\nEach API key can make 5 requests per second and 100 requests per minute. Every response reports your quota:\n\n| Header | Meaning |\n|---|---|\n| `RateLimit-Limit` | Requests allowed in the window |\n| `RateLimit-Remaining` | Requests left in the window |\n| `RateLimit-Reset` | Seconds until the window resets |\n| `Retry-After` | On `429` responses: seconds to wait |\n\n## Errors\n\nErrors use [RFC 7807 problem details](https://datatracker.ietf.org/doc/html/rfc7807) with a stable `code`:\n\n```json\n{\n  \"type\": \"https://api.jetstack.ai/errors/api-key-not-found\",\n  \"title\": \"Invalid API Key\",\n  \"status\": 401,\n  \"detail\": \"The provided API key was not found.\",\n  \"instance\": \"/v1/portals\",\n  \"code\": \"API_KEY_NOT_FOUND\",\n  \"requestId\": \"req_abc123\"\n}\n```\n",
    "contact": {
      "name": "Jetstack AI",
      "url": "https://jetstack.ai/contact"
    }
  },
  "servers": [
    {
      "url": "https://api.jetstack.ai",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "API health and key information"
    },
    {
      "name": "Portals",
      "description": "HubSpot portal management"
    },
    {
      "name": "HubSpot",
      "description": "Browse HubSpot portal assets"
    },
    {
      "name": "Import",
      "description": "Import assets from HubSpot"
    },
    {
      "name": "Tasks",
      "description": "Background task management"
    },
    {
      "name": "Assets",
      "description": "Jetstack asset library"
    },
    {
      "name": "Modules",
      "description": "Playbooks and modules"
    },
    {
      "name": "Mapping",
      "description": "Deployment mapping configuration"
    },
    {
      "name": "Deploy",
      "description": "Deploy assets to HubSpot portals"
    },
    {
      "name": "Audit Blocks",
      "description": "Available audit check blocks"
    },
    {
      "name": "Audit Templates",
      "description": "Reusable audit template management"
    },
    {
      "name": "Audit Runs",
      "description": "Run and retrieve HubSpot audits"
    },
    {
      "name": "Profiles",
      "description": "Asset profile extraction, search, and scanning"
    }
  ],
  "paths": {
    "/v1/health": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "getHealth",
        "summary": "Health check",
        "description": "Returns the API status and information about the authenticated API key,\nincluding its scopes and organization.\n",
        "tags": [
          "Health"
        ],
        "responses": {
          "200": {
            "description": "API is healthy",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                },
                "example": {
                  "data": {
                    "status": "ok",
                    "version": "1.0.0",
                    "orgId": "org_abc123",
                    "keyPrefix": "jsai_xyz...ab12",
                    "scopes": [
                      "assets:read",
                      "portals:read"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/portals": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "listPortals",
        "summary": "List HubSpot portals",
        "description": "Returns all HubSpot portals connected to your organization.",
        "tags": [
          "Portals"
        ],
        "security": [
          {
            "bearerAuth": [
              "portals:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "List of portals",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PortalListResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/hubspot/{portalId}/{assetType}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "browseHubSpot",
        "summary": "Browse HubSpot assets",
        "description": "Fetches assets of a given type from a connected HubSpot portal.\n\n**Supported asset types:**\n`workflows`, `forms`, `emails`, `lists`, `pipelines`, `pages`,\n`templates`, `blogPosts`, `hubdbTables`, `properties`,\n`propertyGroups`, `customObjects`\n",
        "tags": [
          "HubSpot"
        ],
        "security": [
          {
            "bearerAuth": [
              "hubspot:browse"
            ]
          }
        ],
        "parameters": [
          {
            "name": "portalId",
            "in": "path",
            "required": true,
            "description": "HubSpot portal ID (e.g. `12345678`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetType",
            "in": "path",
            "required": true,
            "description": "Type of HubSpot asset to fetch",
            "schema": {
              "type": "string",
              "enum": [
                "workflows",
                "forms",
                "emails",
                "lists",
                "pipelines",
                "pages",
                "templates",
                "blogPosts",
                "hubdbTables",
                "properties",
                "propertyGroups",
                "customObjects"
              ]
            }
          },
          {
            "name": "objectType",
            "in": "query",
            "required": false,
            "description": "Object type filter (used for `properties` and `customObjects`)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Asset list from HubSpot",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/import/start": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "operationId": "startImport",
        "summary": "Start asset import",
        "description": "Initiates an import of assets from a HubSpot portal into the Jetstack asset library.",
        "tags": [
          "Import"
        ],
        "security": [
          {
            "bearerAuth": [
              "hubspot:import"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ImportStartInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Import task created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "listTasks",
        "summary": "List tasks",
        "description": "Returns background tasks for your organization, with optional filters.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "bearerAuth": [
              "tasks:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by task type (e.g. `import`, `deployment`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by status (e.g. `pending`, `running`, `completed`, `failed`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results (default 20)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          },
          {
            "name": "startAfter",
            "in": "query",
            "required": false,
            "description": "Cursor for pagination (task ID from previous page)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of tasks",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/tasks/{taskId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "getTask",
        "summary": "Get task",
        "description": "Returns details and current status of a specific background task.",
        "tags": [
          "Tasks"
        ],
        "security": [
          {
            "bearerAuth": [
              "tasks:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "description": "Task ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/assets": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "listAssets",
        "summary": "List assets",
        "description": "Returns assets in your organization's Jetstack library.",
        "tags": [
          "Assets"
        ],
        "security": [
          {
            "bearerAuth": [
              "assets:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by asset type",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "portalId",
            "in": "query",
            "required": false,
            "description": "Filter by source HubSpot portal ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results (default 20)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "startAfter",
            "in": "query",
            "required": false,
            "description": "Cursor for pagination (asset ID from previous page)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of assets",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/modules": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "listModules",
        "summary": "List modules",
        "description": "Returns playbooks (modules) available in your organization.",
        "tags": [
          "Modules"
        ],
        "security": [
          {
            "bearerAuth": [
              "modules:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results (default 20)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "startAfter",
            "in": "query",
            "required": false,
            "description": "Cursor for pagination (module ID from previous page)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of modules",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/modules/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "getModule",
        "summary": "Get module",
        "description": "Returns details of a specific playbook or module.",
        "tags": [
          "Modules"
        ],
        "security": [
          {
            "bearerAuth": [
              "modules:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Module ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Module details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/mapping/structure": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "operationId": "getMappingStructure",
        "summary": "Get mapping structure",
        "description": "Returns the mapping structure required to deploy assets to a HubSpot portal.",
        "tags": [
          "Mapping"
        ],
        "security": [
          {
            "bearerAuth": [
              "hubspot:deploy"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MappingStructureInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Mapping structure",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/mapping/destinations": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "operationId": "getMappingDestinations",
        "summary": "Get mapping destinations",
        "description": "Returns available destination options for a given mapping configuration.",
        "tags": [
          "Mapping"
        ],
        "security": [
          {
            "bearerAuth": [
              "hubspot:deploy"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MappingDestinationsInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Available mapping destinations",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/deploy/start": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "post": {
        "operationId": "startDeployment",
        "summary": "Start deployment",
        "description": "Initiates a deployment of assets from the Jetstack library to a HubSpot portal.\nReturns a task ID — poll `GET /v1/tasks/{taskId}` to track progress.\n",
        "tags": [
          "Deploy"
        ],
        "security": [
          {
            "bearerAuth": [
              "hubspot:deploy"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeployStartInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Deployment task created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/audit/blocks": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "listAuditBlocks",
        "summary": "List audit blocks",
        "description": "Returns available audit check blocks that can be included in audit templates.",
        "tags": [
          "Audit Blocks"
        ],
        "security": [
          {
            "bearerAuth": [
              "audit:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "reportType",
            "in": "query",
            "required": false,
            "description": "Filter by report type",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "category",
            "in": "query",
            "required": false,
            "description": "Filter by category",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "essentialOnly",
            "in": "query",
            "required": false,
            "description": "Return only essential blocks",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "defaultOnly",
            "in": "query",
            "required": false,
            "description": "Return only default blocks",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of audit blocks",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/audit/templates": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "listAuditTemplates",
        "summary": "List audit templates",
        "description": "Returns audit templates belonging to your organization.",
        "tags": [
          "Audit Templates"
        ],
        "security": [
          {
            "bearerAuth": [
              "audit:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results (default 20)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "startAfter",
            "in": "query",
            "required": false,
            "description": "Cursor for pagination (template ID from previous page)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of audit templates",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "createAuditTemplate",
        "summary": "Create audit template",
        "description": "Creates a new reusable audit template.",
        "tags": [
          "Audit Templates"
        ],
        "security": [
          {
            "bearerAuth": [
              "audit:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAuditTemplateInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Audit template created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/audit/templates/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "getAuditTemplate",
        "summary": "Get audit template",
        "description": "Returns details of a specific audit template.",
        "tags": [
          "Audit Templates"
        ],
        "security": [
          {
            "bearerAuth": [
              "audit:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Audit template ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit template details",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/audit/runs": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "listAuditRuns",
        "summary": "List audit runs",
        "description": "Returns audit runs for your organization, with optional status filter.",
        "tags": [
          "Audit Runs"
        ],
        "security": [
          {
            "bearerAuth": [
              "audit:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by status (`created`, `pending_data_capture`, `processing`, `completed`, `failed`)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of results (default 20)",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "startAfter",
            "in": "query",
            "required": false,
            "description": "Cursor for pagination (audit run ID from previous page)",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of audit runs",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      },
      "post": {
        "operationId": "createAuditRun",
        "summary": "Start audit run",
        "description": "Starts a new audit run against a HubSpot portal.\n\nPortal name and tier are resolved automatically from the portal ID — you\ndo not need to provide them. Use the `id` or `portalId` field from\n`GET /v1/portals` as the `portalId` value.\n",
        "tags": [
          "Audit Runs"
        ],
        "security": [
          {
            "bearerAuth": [
              "audit:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAuditRunInput"
              },
              "example": {
                "portalId": "12345678",
                "templateId": "template_abc"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Audit run created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/audit/runs/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "getAuditRun",
        "summary": "Get audit run",
        "description": "Returns the current status of an audit run. Poll this endpoint until\n`status` is `completed` or `failed`, then fetch results with\n`GET /v1/audit/runs/{id}/data`.\n",
        "tags": [
          "Audit Runs"
        ],
        "security": [
          {
            "bearerAuth": [
              "audit:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Audit run ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Audit run status",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/audit/runs/{id}/data": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "getAuditRunData",
        "summary": "Get audit results",
        "description": "Returns the full audit report data including block definitions, data\npoints, and health scores. Only available once the run has `status: completed`.\n\nIf the run is still processing, a `409 Conflict` is returned with a\nmessage to keep polling `GET /v1/audit/runs/{id}`.\n",
        "tags": [
          "Audit Runs"
        ],
        "security": [
          {
            "bearerAuth": [
              "audit:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "description": "Audit run ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Full audit report data",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GenericDataResponse"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/InvalidInstance"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "Audit run not yet completed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/v1/assets/profiles": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        }
      ],
      "get": {
        "operationId": "listLibraryProfiles",
        "summary": "Search library asset profiles",
        "description": "Returns structured profiles for imported assets in the Jetstack library.\nProfiles include properties referenced, dependencies, enrollment criteria,\nactions, and other metadata enabling AI-driven matching against use cases.\n",
        "tags": [
          "Profiles"
        ],
        "security": [
          {
            "bearerAuth": [
              "assets:read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Filter by asset type: workflows, lists, forms, emails, pipelines",
            "schema": {
              "type": "string",
              "enum": [
                "workflows",
                "lists",
                "forms",
                "emails",
                "pipelines"
              ]
            }
          },
          {
            "name": "objectType",
            "in": "query",
            "required": false,
            "description": "Filter by object type (e.g. Contact, Deal, 0-1)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "portalId",
            "in": "query",
            "required": false,
            "description": "Filter by source portal ID",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Maximum number of profiles to return (default 200)",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of asset profiles",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProfileListResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/hubspot/{portalId}/{assetType}/profiles": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "portalId",
          "in": "path",
          "required": true,
          "description": "Jetstack portal ID",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "assetType",
          "in": "path",
          "required": true,
          "description": "Asset type to scan",
          "schema": {
            "type": "string",
            "enum": [
              "workflows",
              "lists",
              "forms",
              "emails",
              "pipelines"
            ]
          }
        }
      ],
      "get": {
        "operationId": "scanPortalProfiles",
        "summary": "Scan HubSpot portal for asset profiles",
        "description": "Fetches assets from a connected HubSpot portal, extracts structured profiles,\nand caches results for 24 hours. Use \\`fresh=true\\` to bypass cache and fetch\nlive data from HubSpot.\n",
        "tags": [
          "Profiles"
        ],
        "security": [
          {
            "bearerAuth": [
              "hubspot:browse"
            ]
          }
        ],
        "parameters": [
          {
            "name": "objectType",
            "in": "query",
            "required": false,
            "description": "Filter by object type (e.g. Contact, Deal)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fresh",
            "in": "query",
            "required": false,
            "description": "Force fresh fetch from HubSpot, bypassing 24h cache",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Scanned asset profiles",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanPortalProfilesResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/hubspot/scan/{assetType}/profiles": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "assetType",
          "in": "path",
          "required": true,
          "description": "Asset type to scan across all portals",
          "schema": {
            "type": "string",
            "enum": [
              "workflows",
              "lists",
              "forms",
              "emails",
              "pipelines"
            ]
          }
        }
      ],
      "get": {
        "operationId": "scanAllPortalsProfiles",
        "summary": "Scan all portals for asset profiles",
        "description": "Scans ALL connected HubSpot portals and returns asset profiles.\nUseful for cross-account discovery (e.g., finding the best MQL workflow\nacross all client accounts). Results are cached per-portal for 24 hours.\n",
        "tags": [
          "Profiles"
        ],
        "security": [
          {
            "bearerAuth": [
              "hubspot:browse"
            ]
          }
        ],
        "parameters": [
          {
            "name": "objectType",
            "in": "query",
            "required": false,
            "description": "Filter by object type (e.g. Contact, Deal)",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fresh",
            "in": "query",
            "required": false,
            "description": "Force fresh fetch from HubSpot, bypassing 24h cache",
            "schema": {
              "type": "string",
              "enum": [
                "true",
                "false"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Profiles from all connected portals",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanAllPortalsProfilesResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          }
        }
      }
    },
    "/v1/assets/{type}/{id}/detail": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "type",
          "in": "path",
          "required": true,
          "description": "Asset type",
          "schema": {
            "type": "string",
            "enum": [
              "workflows",
              "lists",
              "forms",
              "emails",
              "pipelines"
            ]
          }
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Library asset ID",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "getAssetDetail",
        "summary": "Get full asset detail",
        "description": "Returns the complete raw data for an imported asset including the full\nHubSpot schema, extracted dependencies, and object schemas. Use this\nafter finding a match via profiles to inspect the full asset before deployment.\n",
        "tags": [
          "Profiles"
        ],
        "security": [
          {
            "bearerAuth": [
              "assets:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Full asset detail",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssetDetailResponse"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Asset not found"
          }
        }
      }
    },
    "/v1/assets/workflows/{id}/mermaid": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "id",
          "in": "path",
          "required": true,
          "description": "Library asset ID of an imported workflow",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "getWorkflowMermaid",
        "summary": "Get a Mermaid diagram for an imported workflow",
        "description": "Returns the workflow as a Mermaid flowchart. The diagram is generated once and cached on the asset.",
        "tags": [
          "Assets"
        ],
        "security": [
          {
            "bearerAuth": [
              "assets:read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Mermaid diagram",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "mermaid",
                        "cached"
                      ],
                      "properties": {
                        "mermaid": {
                          "type": "string",
                          "description": "Mermaid flowchart source"
                        },
                        "cached": {
                          "type": "boolean",
                          "description": "True when served from the stored diagram"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Workflow not found"
          }
        }
      }
    },
    "/v1/hubspot/{portalId}/workflows/{workflowId}/mermaid": {
      "parameters": [
        {
          "$ref": "#/components/parameters/InstanceId"
        },
        {
          "name": "portalId",
          "in": "path",
          "required": true,
          "description": "Jetstack portal ID or HubSpot portal ID",
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "workflowId",
          "in": "path",
          "required": true,
          "description": "HubSpot workflow ID",
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "previewWorkflowMermaid",
        "summary": "Preview a HubSpot workflow as a Mermaid diagram",
        "description": "Reads a workflow straight from the connected portal, without importing it, and returns it as a Mermaid flowchart.",
        "tags": [
          "HubSpot"
        ],
        "security": [
          {
            "bearerAuth": [
              "hubspot:browse"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Mermaid diagram",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "required": [
                        "mermaid",
                        "workflowName",
                        "workflowId",
                        "isEnabled",
                        "actionCount"
                      ],
                      "properties": {
                        "mermaid": {
                          "type": "string"
                        },
                        "workflowName": {
                          "type": "string"
                        },
                        "workflowId": {
                          "type": "string"
                        },
                        "isEnabled": {
                          "type": "boolean"
                        },
                        "actionCount": {
                          "type": "integer"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "description": "Portal or workflow not found"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key generated in **Settings → Access Tokens**. Keys have the prefix\n`jsai_` and carry scopes that determine what they can access.\n"
      }
    },
    "parameters": {
      "InstanceId": {
        "name": "X-Instance-Id",
        "in": "header",
        "required": false,
        "description": "Only for organizations on a dedicated Jetstack instance: the Instance ID shown in **Settings → Access Tokens → Connection Details**. Leave it out (or send `default`) otherwise.",
        "schema": {
          "type": "string",
          "example": "default"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Client-generated unique key (UUID recommended) to make POST mutations\nidempotent. If you send the same key within 24 hours, the original\nresponse is replayed and no duplicate action is taken. The response\nwill include `Idempotent-Replayed: true` on replays.\n",
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "schemas": {
      "HealthResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "status": {
                "type": "string",
                "enum": [
                  "ok"
                ]
              },
              "version": {
                "type": "string",
                "example": "1.0.0"
              },
              "orgId": {
                "type": "string",
                "description": "Your Jetstack organization ID"
              },
              "keyPrefix": {
                "type": "string",
                "description": "Prefix of the API key used (e.g. `jsai_abc...xyz`)"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/ApiKeyScope"
                }
              }
            }
          }
        }
      },
      "PortalListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/PortalSummary"
                }
              },
              "total": {
                "type": "integer"
              },
              "hasMore": {
                "type": "boolean"
              },
              "lastId": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      },
      "PortalSummary": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Jetstack ID"
          },
          "portalId": {
            "type": "string",
            "description": "HubSpot portal ID"
          },
          "name": {
            "type": "string",
            "description": "Portal display name"
          },
          "domain": {
            "type": "string",
            "nullable": true
          }
        }
      },
      "PaginatedResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "items": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "total": {
                "type": "integer"
              },
              "hasMore": {
                "type": "boolean"
              },
              "lastId": {
                "type": "string",
                "nullable": true
              }
            }
          }
        }
      },
      "GenericDataResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object"
          }
        }
      },
      "ImportStartInput": {
        "type": "object",
        "required": [
          "portalId",
          "assetTypes"
        ],
        "properties": {
          "portalId": {
            "type": "string",
            "description": "HubSpot portal ID to import from"
          },
          "assetTypes": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Asset types to import (e.g. `[\"workflows\", \"forms\"]`)"
          },
          "userName": {
            "type": "string",
            "description": "Optional display name for audit trail (defaults to key owner)"
          }
        }
      },
      "MappingStructureInput": {
        "type": "object",
        "required": [
          "assetIds",
          "targetPortalId"
        ],
        "properties": {
          "assetIds": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "IDs of assets to deploy"
          },
          "targetPortalId": {
            "type": "string",
            "description": "Destination HubSpot portal ID"
          }
        }
      },
      "MappingDestinationsInput": {
        "type": "object",
        "properties": {
          "targetPortalId": {
            "type": "string"
          },
          "mappingStructure": {
            "type": "object",
            "description": "Mapping structure returned from `POST /v1/mapping/structure`"
          }
        }
      },
      "DeployStartInput": {
        "type": "object",
        "required": [
          "assetIds",
          "targetPortalId",
          "mapping"
        ],
        "properties": {
          "assetIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "targetPortalId": {
            "type": "string"
          },
          "mapping": {
            "type": "object",
            "description": "Resolved mapping from `/v1/mapping/destinations`"
          },
          "userName": {
            "type": "string",
            "description": "Optional display name for audit trail"
          }
        }
      },
      "CreateAuditTemplateInput": {
        "type": "object",
        "required": [
          "name",
          "blocks"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "Template display name"
          },
          "blocks": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Array of audit block IDs to include"
          }
        }
      },
      "CreateAuditRunInput": {
        "type": "object",
        "required": [
          "portalId"
        ],
        "properties": {
          "portalId": {
            "type": "string",
            "description": "HubSpot portal ID (or Jetstack portal ID) — use the `id` or\n`portalId` field from `GET /v1/portals`\n"
          },
          "templateId": {
            "type": "string",
            "description": "Optional audit template ID. If omitted, uses the default template."
          }
        }
      },
      "ApiKeyScope": {
        "type": "string",
        "description": "Permission scope for API key access",
        "enum": [
          "assets:read",
          "assets:write",
          "modules:read",
          "modules:write",
          "tasks:read",
          "mapping:read",
          "portals:read",
          "hubspot:browse",
          "hubspot:import",
          "hubspot:deploy",
          "mapping:validate",
          "audit:read",
          "audit:write",
          "projects:read",
          "projects:write",
          "projects:chat",
          "projects:generate",
          "projects:deploy",
          "projects:admin",
          "projects:billing"
        ]
      },
      "ProfileListResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "profiles": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AssetProfile"
                }
              },
              "total": {
                "type": "integer"
              },
              "meta": {
                "$ref": "#/components/schemas/ProfileResponseMeta"
              }
            }
          }
        }
      },
      "ScanPortalProfilesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "profiles": {
                "type": "array",
                "items": {
                  "$ref": "#/components/schemas/AssetProfile"
                }
              },
              "total": {
                "type": "integer"
              },
              "meta": {
                "$ref": "#/components/schemas/ProfileResponseMeta"
              }
            }
          }
        }
      },
      "ScanAllPortalsProfilesResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "portals": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "portalId": {
                      "type": "string"
                    },
                    "portalName": {
                      "type": "string"
                    },
                    "profiles": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/AssetProfile"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/ProfileResponseMeta"
                    }
                  }
                }
              },
              "totalProfiles": {
                "type": "integer"
              }
            }
          }
        }
      },
      "AssetDetailResponse": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "assetType": {
                "type": "string"
              },
              "data": {
                "type": "object",
                "description": "Raw HubSpot asset data"
              },
              "metadata": {
                "type": "object",
                "description": "Import metadata including dependencies"
              }
            }
          }
        }
      },
      "ProfileResponseMeta": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "cache",
              "hubspot",
              "library"
            ],
            "description": "Where the profiles came from"
          },
          "cachedAt": {
            "type": "string",
            "format": "date-time"
          },
          "fetchedAt": {
            "type": "string",
            "format": "date-time"
          },
          "age": {
            "type": "string",
            "description": "Human-readable cache age (e.g. 2h 15m)"
          },
          "totalProfiles": {
            "type": "integer"
          },
          "portalName": {
            "type": "string"
          }
        }
      },
      "AssetProfile": {
        "type": "object",
        "description": "Structured summary of a HubSpot asset for AI-driven matching",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "assetType": {
            "type": "string",
            "enum": [
              "workflows",
              "lists",
              "forms",
              "emails",
              "pipelines"
            ]
          },
          "objectType": {
            "type": "string",
            "description": "Human-readable object type (Contact, Deal, Ticket)"
          },
          "objectTypeId": {
            "type": "string",
            "description": "Raw HubSpot object type ID (0-1, 0-3, 0-5)"
          },
          "portalId": {
            "type": "string"
          },
          "portalName": {
            "type": "string"
          },
          "isImported": {
            "type": "boolean",
            "description": "true if in Jetstack library, false if from live HubSpot scan"
          },
          "propertiesReferenced": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "All property names referenced by this asset"
          },
          "dependsOn": {
            "type": "object",
            "description": "Cross-asset and entity dependencies",
            "properties": {
              "lists": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "forms": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "emails": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "workflows": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "pipelines": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "owners": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "lifecycleStages": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "subscriptionTypes": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ProblemDetails": {
        "type": "object",
        "description": "RFC 7807 Problem Details error response",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "example": "https://api.jetstack.ai/errors/api-key-not-found"
          },
          "title": {
            "type": "string",
            "example": "Invalid API Key"
          },
          "status": {
            "type": "integer",
            "example": 401
          },
          "detail": {
            "type": "string",
            "example": "The provided API key was not found."
          },
          "instance": {
            "type": "string",
            "description": "Request path",
            "example": "/v1/portals"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable error code",
            "example": "API_KEY_NOT_FOUND"
          },
          "requestId": {
            "type": "string",
            "example": "req_abc123"
          }
        }
      }
    },
    "responses": {
      "InvalidInstance": {
        "description": "Unknown `X-Instance-Id` header",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://api.jetstack.ai/errors/invalid-instance",
              "title": "Invalid Instance ID",
              "status": 400,
              "detail": "Unknown Instance ID. Use the value in Settings → Access Tokens, or leave the header out."
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing or invalid API key",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://api.jetstack.ai/errors/auth-token-missing",
              "title": "Authentication Required",
              "status": 401,
              "detail": "Authorization header is missing.",
              "code": "AUTH_TOKEN_MISSING"
            }
          }
        }
      },
      "Forbidden": {
        "description": "API key lacks the required scope",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://api.jetstack.ai/errors/api-key-insufficient-scope",
              "title": "Insufficient Permissions",
              "status": 403,
              "detail": "Missing required scope: portals:read",
              "code": "API_KEY_INSUFFICIENT_SCOPE"
            }
          }
        }
      },
      "NotFound": {
        "description": "Resource not found",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "BadRequest": {
        "description": "Invalid request parameters",
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded",
        "headers": {
          "Retry-After": {
            "description": "Seconds to wait before retrying",
            "schema": {
              "type": "integer"
            }
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/ProblemDetails"
            },
            "example": {
              "type": "https://api.jetstack.ai/errors/api-key-rate-limited",
              "title": "Rate Limit Exceeded",
              "status": 429,
              "detail": "Rate limit of 100 requests per minute exceeded. Retry after 12 seconds.",
              "code": "API_KEY_RATE_LIMITED"
            }
          }
        }
      }
    }
  }
}
