{
  "openapi": "3.1.0",
  "info": {
    "title": "Jetstack AI — Projects API",
    "version": "1.0.0",
    "description": "Every Projects surface, as a REST API.\n\n**Authorization is two checks, both applied.** The API key carries scopes;\nthe key's *creator* carries a role on each project. A request succeeds only\nwhere the two intersect, so a key can never exceed the person who minted it.\n`GET /v1/projects/{projectId}/access` returns that intersection directly.\n\n**There is no `mode`.** One project is one portal; every call is pinned to\nthe project's production binding.\n\n**Errors are codes, not prose.** Every refusal carries a machine-readable\n`code` in an RFC 7807 problem document. Match on the code, never on the text.\n\n**Some work cannot be done by an API.** Extension-lane deploys and portal\nscans need a signed-in HubSpot tab; those endpoints queue the work, report\nits status, and can cancel it before it starts."
  },
  "servers": [
    {
      "url": "https://api.jetstack.ai"
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "API key (`jsai_…`). Projects scopes: projects:read, projects:write, projects:chat, projects:generate, projects:deploy, projects:admin, projects:billing. `projects:deploy` and `projects:billing` are excluded from every preset and must be granted deliberately."
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 7807 problem document.",
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "Machine-readable refusal code. Match on this."
          },
          "requestId": {
            "type": "string"
          },
          "hint": {
            "type": "string"
          }
        }
      }
    },
    "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"
        }
      }
    }
  },
  "paths": {
    "/v1/projects/openapi.json": {
      "get": {
        "summary": "The OpenAPI document for this surface",
        "description": "Generated from the same route table the router dispatches, so it cannot describe an endpoint that does not exist or omit one that does.\n\n**Scope:** `projects:read`.\n\n**Project capability:** none (not scoped to one project).",
        "tags": [
          "Projects"
        ],
        "operationId": "getV1ProjectsOpenapiJson",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The OpenAPI document for this surface"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/enabled": {
      "get": {
        "summary": "Is Projects enabled for this organization?",
        "description": "The entitlement gate. Every other route 403s with PROJECTS_NOT_ENABLED when this is false.\n\n**Scope:** `projects:read`.\n\n**Project capability:** none (not scoped to one project).",
        "tags": [
          "Access"
        ],
        "operationId": "getV1ProjectsEnabled",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Is Projects enabled for this organization?"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/roles": {
      "get": {
        "summary": "The project role → capability table",
        "description": "Static. A key's effective permission on a project is its scope intersected with the capabilities of the key creator's role, so an agent can predict a refusal from this table plus GET /v1/projects/:projectId/access.\n\n**Scope:** `projects:read`.\n\n**Project capability:** none (not scoped to one project).",
        "tags": [
          "Access"
        ],
        "operationId": "getV1ProjectsRoles",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The project role → capability table"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/access": {
      "get": {
        "summary": "The caller's role, capabilities and available project actions",
        "description": "Wraps `project.getCapabilities`, and adds the API-key view: which of the caller's scopes are present, and the effective intersection. Project-scope actions carry `available` plus `unavailableReason`.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Access"
        ],
        "operationId": "getV1ProjectsProjectIdAccess",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The caller's role, capabilities and available project actions"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/credits": {
      "get": {
        "summary": "Projects credit balance for the organization",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** none (not scoped to one project).",
        "tags": [
          "Credits"
        ],
        "operationId": "getV1ProjectsCredits",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Projects credit balance for the organization"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/credits/history": {
      "get": {
        "summary": "Credit ledger entries, newest first",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** none (not scoped to one project).",
        "tags": [
          "Credits"
        ],
        "operationId": "getV1ProjectsCreditsHistory",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size (default 50).",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Credit ledger entries, newest first"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/credits/purchases": {
      "post": {
        "summary": "Start a credit purchase, returning a Stripe checkout URL",
        "description": "Requires an organization admin. `projects:billing` is excluded from every scope preset, so a key only reaches this route when it was granted deliberately. The checkout itself is completed by a human in a browser.\n\n**Scope:** `projects:billing`.\n\n**Project capability:** none (not scoped to one project).\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `AUTH_PERMISSION_DENIED`, `PROJECTS_NOT_ENABLED`.",
        "tags": [
          "Credits"
        ],
        "operationId": "postV1ProjectsCreditsPurchases",
        "security": [
          {
            "apiKey": [
              "projects:billing"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "retailUsdCents": {
                    "description": "Purchase amount in US cents."
                  },
                  "successUrl": {
                    "description": "Where Stripe returns the buyer on success."
                  },
                  "cancelUrl": {
                    "description": "Where Stripe returns the buyer on cancel."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Start a credit purchase, returning a Stripe checkout URL"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/credits/purchases/{sessionId}": {
      "get": {
        "summary": "Status of a credit purchase",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** none (not scoped to one project).",
        "tags": [
          "Credits"
        ],
        "operationId": "getV1ProjectsCreditsPurchasesSessionId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "sessionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Status of a credit purchase"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/runs/{runId}/resume": {
      "post": {
        "summary": "Resume a run that paused for insufficient credits",
        "description": "The run stays paused until the organization has credits again; this is the restart. Refuses with RUN_NOT_PAUSED when the run is not in a credit pause.\n\n**Scope:** `projects:generate`.\n\n**Project capability:** `asset.materialize` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `RUN_NOT_PAUSED`, `INSUFFICIENT_PROJECT_CREDITS`.",
        "tags": [
          "Runs & receipts"
        ],
        "operationId": "postV1ProjectsProjectIdRunsRunIdResume",
        "security": [
          {
            "apiKey": [
              "projects:generate"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Resume a run that paused for insufficient credits"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects": {
      "get": {
        "summary": "List projects",
        "description": "Search and per-status counts are computed server-side. The UI fetches every page and filters in the browser (`ProjectsListPage.tsx:33-70`), which makes its counts correct only after a full download; `counts` here always describes the whole organization. When a filter is supplied the scan is bounded — `searchTruncated: true` says the walk stopped early rather than returning a short page silently.\n\n**Scope:** `projects:read`.\n\n**Project capability:** none (not scoped to one project).",
        "tags": [
          "Projects"
        ],
        "operationId": "getV1Projects",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Filter by project status.",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "completed",
                "archived"
              ]
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Substring match on name, portal name or portal id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "portalId",
            "in": "query",
            "required": false,
            "description": "Exact HubSpot portal id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size (default 25, max 100).",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "List projects"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "post": {
        "summary": "Create a project",
        "description": "One project is one portal: `portalId` is the production binding and there is no mode. `Idempotency-Key` becomes the handler's own `requestId`, so a retried create collapses inside the handler rather than producing a second project.\n\n**Scope:** `projects:admin`.\n\n**Project capability:** none (not scoped to one project).\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `PROJECTS_NOT_ENABLED`, `PORTAL_NOT_FOUND`.",
        "tags": [
          "Projects"
        ],
        "operationId": "postV1Projects",
        "security": [
          {
            "apiKey": [
              "projects:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "description": "Project name."
                  },
                  "portalId": {
                    "description": "HubSpot portal id to bind as production."
                  },
                  "crmPlatform": {
                    "description": "`hubspot`."
                  },
                  "runAudit": {
                    "description": "Optional. Start the onboarding audit immediately."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Create a project"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}": {
      "get": {
        "summary": "Get a project",
        "description": "The project document, plus the fields the UI reads off it separately: the production binding, members, the Knowledge pointer, Blueprint lifecycle fields and counts.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Projects"
        ],
        "operationId": "getV1ProjectsProjectId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Get a project"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "patch": {
        "summary": "Rename a project",
        "description": "**Scope:** `projects:admin`.\n\n**Project capability:** `project.settings` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Projects"
        ],
        "operationId": "patchV1ProjectsProjectId",
        "security": [
          {
            "apiKey": [
              "projects:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "description": "New project name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Rename a project"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "delete": {
        "summary": "Archive a project",
        "description": "Archive, not destroy — deployed objects stay in HubSpot and the project's history is retained. There is no unarchive path anywhere in the product today.\n\n**Scope:** `projects:admin`.\n\n**Project capability:** `project.settings` — held by the key creator's role on this project.",
        "tags": [
          "Projects"
        ],
        "operationId": "deleteV1ProjectsProjectId",
        "security": [
          {
            "apiKey": [
              "projects:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Archive a project"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/overview": {
      "get": {
        "summary": "Everything the Home tab shows, as data",
        "description": "Action items, asset standing, portal pulse and coverage, the latest run, active and last-completed release, Knowledge review counts, roster headcount, Blueprint lifecycle and onboarding status — each from the same helper the UI uses. Sources that could not be read are named in `unavailable` rather than being reported as zero.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Projects"
        ],
        "operationId": "getV1ProjectsProjectIdOverview",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Everything the Home tab shows, as data"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/members": {
      "get": {
        "summary": "Project members and their roles",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Members"
        ],
        "operationId": "getV1ProjectsProjectIdMembers",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Project members and their roles"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "post": {
        "summary": "Add a member",
        "description": "**Scope:** `projects:admin`.\n\n**Project capability:** `members` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `AUTH_PERMISSION_DENIED`.",
        "tags": [
          "Members"
        ],
        "operationId": "postV1ProjectsProjectIdMembers",
        "security": [
          {
            "apiKey": [
              "projects:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "userId": {
                    "description": "User ID, from the member candidates endpoint."
                  },
                  "role": {
                    "description": "`owner`, `editor` or `viewer`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Add a member"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/members/candidates": {
      "get": {
        "summary": "Organization members who could be added",
        "description": "People in your organization who aren't members yet. Anyone with a read-only organization role can only be added as a `viewer`.\n\n**Scope:** `projects:admin`.\n\n**Project capability:** `members` — held by the key creator's role on this project.",
        "tags": [
          "Members"
        ],
        "operationId": "getV1ProjectsProjectIdMembersCandidates",
        "security": [
          {
            "apiKey": [
              "projects:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Name or email substring.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size (max 100).",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "description": "Offset into the directory.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Organization members who could be added"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/members/{userId}": {
      "patch": {
        "summary": "Change a member's role",
        "description": "**Scope:** `projects:admin`.\n\n**Project capability:** `members` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Members"
        ],
        "operationId": "patchV1ProjectsProjectIdMembersUserId",
        "security": [
          {
            "apiKey": [
              "projects:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "role": {
                    "description": "`owner`, `editor` or `viewer`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Change a member's role"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "delete": {
        "summary": "Remove a member",
        "description": "**Scope:** `projects:admin`.\n\n**Project capability:** `members` — held by the key creator's role on this project.",
        "tags": [
          "Members"
        ],
        "operationId": "deleteV1ProjectsProjectIdMembersUserId",
        "security": [
          {
            "apiKey": [
              "projects:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Remove a member"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal": {
      "get": {
        "summary": "The portal twin",
        "description": "Plan and limits, **all** portal users (the UI shows 25), granted scopes, per-domain sweeps with staleness, the scan gate, connected domains, findings, and the inventory including `staleDomains`.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortal",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The portal twin"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "put": {
        "summary": "Bind the project's portal",
        "description": "One project is one portal, so this binds the production slot and refuses when the project is already bound — rebinding would leave objects already deployed claimed in a portal the project no longer names.\n\n**Scope:** `projects:admin`.\n\n**Project capability:** `portal.connect` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `PROJECT_PORTAL_ALREADY_BOUND`, `PORTAL_NOT_FOUND`.",
        "tags": [
          "Portal"
        ],
        "operationId": "putV1ProjectsProjectIdPortal",
        "security": [
          {
            "apiKey": [
              "projects:admin"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "portalId": {
                    "description": "HubSpot portal id, already connected to the org."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Bind the project's portal"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/onboarding": {
      "get": {
        "summary": "Onboarding audit state, and whether the workspace is usable",
        "description": "`workspaceReady` is the gate the UI applies before it lets anyone work. The browser fails **open** when the gate errors (`ProjectAuditGate.tsx:48-54`); this endpoint does not — an unreadable gate is reported as unknown, never as ready.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortalOnboarding",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Onboarding audit state, and whether the workspace is usable"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/rescan": {
      "post": {
        "summary": "Re-read the portal",
        "description": "Queues a durable API sweep and, for the extension lane, work that a human must run from a signed-in HubSpot tab. Returns the refresh id to poll.\n\n**Scope:** `projects:write`.\n\n**Project capability:** `chat.write` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Portal"
        ],
        "operationId": "postV1ProjectsProjectIdPortalRescan",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "lanes": {
                    "description": "Optional. `api`, `extension`, or both. Defaults to both."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Re-read the portal"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/refreshes/current": {
      "get": {
        "summary": "The in-flight (or most recent) portal refresh",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortalRefreshesCurrent",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "refreshId",
            "in": "query",
            "required": false,
            "description": "A specific refresh instead of the current one.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The in-flight (or most recent) portal refresh"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/scan-gate": {
      "get": {
        "summary": "Whether an extension-lane scan can run, and what is missing",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortalScanGate",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Whether an extension-lane scan can run, and what is missing"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/scan": {
      "post": {
        "summary": "Queue an extension-lane portal scan",
        "description": "Queues chunks into the HubSpot Projects inbox. **A human must drain them** from a signed-in HubSpot tab with the extension open; this call cannot perform the scan, only ask for it.\n\n**Scope:** `projects:write`.\n\n**Project capability:** `chat.write` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Portal"
        ],
        "operationId": "postV1ProjectsProjectIdPortalScan",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Queue an extension-lane portal scan"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/objects": {
      "get": {
        "summary": "Objects observed in the portal",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortalObjects",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "query",
            "required": false,
            "description": "Twin domain, e.g. `workflow`, `property`, `owner`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Substring match on the object's name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hubspotId",
            "in": "query",
            "required": false,
            "description": "Exact HubSpot id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Objects observed in the portal"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/objects/{domain}/{hubspotId}": {
      "get": {
        "summary": "One observed object — preview, facts and provenance",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortalObjectsDomainHubspotId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "domain",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hubspotId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One observed object — preview, facts and provenance"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/relationships/summary": {
      "get": {
        "summary": "Relationship graph summary",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortalRelationshipsSummary",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Substring match on node label.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "nodeKinds",
            "in": "query",
            "required": false,
            "description": "Repeatable or comma-separated node kinds.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Relationship graph summary"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal/relationships/neighborhood": {
      "get": {
        "summary": "One object's neighbourhood in the relationship graph",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortalRelationshipsNeighborhood",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Twin domain of the anchor object.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "hubspotId",
            "in": "query",
            "required": false,
            "description": "HubSpot id of the anchor object.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "`incoming`, `outgoing` or both.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "nodeKinds",
            "in": "query",
            "required": false,
            "description": "Filter neighbours by kind.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "relations",
            "in": "query",
            "required": false,
            "description": "Filter by relationship kind.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "resolutions",
            "in": "query",
            "required": false,
            "description": "Filter by how the reference resolved.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "provenance",
            "in": "query",
            "required": false,
            "description": "`portal-owned`, `current-project`, `organization`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "incomingCursor",
            "in": "query",
            "required": false,
            "description": "Page the incoming edges.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "outgoingCursor",
            "in": "query",
            "required": false,
            "description": "Page the outgoing edges.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Edges per direction.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One object's neighbourhood in the relationship graph"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/documents": {
      "post": {
        "summary": "Upload a document (multipart) and start its analysis",
        "description": "One file per request, in a `file` field — the upstream endpoint is single-file by design, so one bad file 400s on its own instead of sinking a batch. Passed straight through to projects-ai, which stores the bytes and hashes them; a duplicate answers `reused: true` with the existing document rather than storing it twice. Like the browser, the upload then starts document analysis (spends credits; needs `projects:generate`) and returns `analysis: { started, operationId }` — poll `/operations/:operationId`. `?analyze=false` stores only; `?chatId=` names the chat the analysis is posted into (required to start it). A key without `projects:generate`, or a request without `chatId`, still uploads and gets `analysis.started: false` with the reason.\n\n**Scope:** `projects:chat`.\n\n**Project capability:** `chat.send` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Documents"
        ],
        "operationId": "postV1ProjectsProjectIdDocuments",
        "security": [
          {
            "apiKey": [
              "projects:chat"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "analyze",
            "in": "query",
            "required": false,
            "description": "`false` to store without starting analysis.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chatId",
            "in": "query",
            "required": false,
            "description": "The chat the analysis is posted into.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Upload a document (multipart) and start its analysis"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "get": {
        "summary": "List uploaded documents",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Documents"
        ],
        "operationId": "getV1ProjectsProjectIdDocuments",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Substring match on file name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Analysis status filter.",
            "schema": {
              "type": "string",
              "enum": [
                "pending",
                "queued",
                "analyzing",
                "ready",
                "failed"
              ]
            }
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "`newest`, `oldest` or `name`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "List uploaded documents"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/documents/{documentId}": {
      "get": {
        "summary": "One document — extraction and analysis detail",
        "description": "The whole stored record: extraction state, analysis state and its errors, section map, `insightsExtracted`, and the versions it produced. The list view carries a summary of this; an agent deciding whether to re-run analysis needs the errors.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `DOCUMENT_NOT_FOUND`.",
        "tags": [
          "Documents"
        ],
        "operationId": "getV1ProjectsProjectIdDocumentsDocumentId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "documentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One document — extraction and analysis detail"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/documents/{documentId}/download": {
      "get": {
        "summary": "A signed download URL for the original file",
        "description": "The URL expires in five minutes.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Documents"
        ],
        "operationId": "getV1ProjectsProjectIdDocumentsDocumentIdDownload",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "documentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "A signed download URL for the original file"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/documents/analyze": {
      "post": {
        "summary": "Analyze documents into Project Knowledge",
        "description": "Spends credits. Creates a durable operation and returns its id; poll `/operations/:operationId`. The handler is idempotent on the content of the request (documents + instructions + chat), so re-sending the same analysis returns the in-flight operation with `created: false` rather than starting a second one. This is also the retry path for a failed analysis.\n\n**Scope:** `projects:generate`.\n\n**Project capability:** `asset.materialize` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `DOCUMENT_ANALYSIS_LIMIT`, `INSUFFICIENT_PROJECT_CREDITS`.",
        "tags": [
          "Documents"
        ],
        "operationId": "postV1ProjectsProjectIdDocumentsAnalyze",
        "security": [
          {
            "apiKey": [
              "projects:generate"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "documentIds": {
                    "description": "Up to 10 document ids."
                  },
                  "instructions": {
                    "description": "Optional steer, at most 10000 characters."
                  },
                  "chatId": {
                    "description": "The chat the analysis request and its answer are posted into."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Analyze documents into Project Knowledge"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/operations": {
      "get": {
        "summary": "Durable operations (document analysis, chat capture, planning)",
        "description": "Background operations on this project. `active=true` returns only the ones still in flight, which is how an agent waits for work it started.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Documents"
        ],
        "operationId": "getV1ProjectsProjectIdOperations",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "e.g. `document_analysis`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "active",
            "in": "query",
            "required": false,
            "description": "`true` for in-flight only.",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Durable operations (document analysis, chat capture, planning)"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/operations/{operationId}": {
      "get": {
        "summary": "One operation's full progress",
        "description": "`queued → extracting → analyzing → merging → answer_queued → answering → succeeded | partial | failed`, with per-batch progress, `documentFailures`, the `resultSummary`, the Knowledge version it published and the id of the follow-up answer message.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `OPERATION_NOT_FOUND`.",
        "tags": [
          "Documents"
        ],
        "operationId": "getV1ProjectsProjectIdOperationsOperationId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "operationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One operation's full progress"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/coverage": {
      "get": {
        "summary": "Requirement coverage, including uncovered demands and separate runtime acceptance",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeCoverage",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Requirement coverage, including uncovered demands and separate runtime acceptance"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge": {
      "get": {
        "summary": "The published Project brief — pointer, summary and metrics",
        "description": "The compiled client context: the company/team/process summary projection, review breakdowns by level, identity-queue counts, analysis-quality metrics and the roster classification. Refuses with KNOWLEDGE_NOT_COMPILED rather than returning an empty brief that reads like 'this client has no context'.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `KNOWLEDGE_NOT_COMPILED`.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledge",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The published Project brief — pointer, summary and metrics"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/brief": {
      "get": {
        "summary": "Every brief item",
        "description": "Including the `briefItems` overflow subcollection, which the version document only counts once a brief exceeds 300 items.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeBrief",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "company, stakeholder, process, requirement, external_system, question, conflict.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reviewState",
            "in": "query",
            "required": false,
            "description": "confirmed, source_backed, needs_review, conflicting.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Every brief item"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/versions": {
      "get": {
        "summary": "Published Knowledge versions, newest first",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeVersions",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Published Knowledge versions, newest first"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/versions/{version}": {
      "get": {
        "summary": "One immutable Knowledge version, in full",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeVersionsVersion",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One immutable Knowledge version, in full"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/claims": {
      "get": {
        "summary": "The claims behind the brief, with their evidence",
        "description": "Each claim carries `sourceRefs` (document / chat / audit / portal / user_review, with locator and excerpt), its status, what superseded it and why it was rejected. This is the evidence layer the brief summarizes.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `KNOWLEDGE_NOT_COMPILED`.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeClaims",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "entityId",
            "in": "query",
            "required": false,
            "description": "Restrict to one subject entity.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "accepted, needs_review, rejected, superseded.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size (max 500).",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The claims behind the brief, with their evidence"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/decisions": {
      "get": {
        "summary": "The unified decision queue",
        "description": "Conflicts, facts, questions, dependencies, inferred claims and identity rows in one list, across `required | follow_up | informational`. Each decision carries the claim ids the write needs, the resolutions it permits, the conflict options, merge candidates and the evidence — so a caller never assembles claim ids itself. Conflict-overlap suppression is applied: an item whose claims a conflict already covers is not offered separately.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeDecisions",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "level",
            "in": "query",
            "required": false,
            "description": "required, follow_up or informational.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Brief item kind.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "identity",
            "in": "query",
            "required": false,
            "description": "`true` for identity decisions only.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The unified decision queue"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/decisions/{decisionId}": {
      "get": {
        "summary": "One decision",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `KNOWLEDGE_DECISION_NOT_FOUND`.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeDecisionsDecisionId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "decisionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One decision"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/decisions/{decisionId}/resolve": {
      "post": {
        "summary": "Resolve one decision",
        "description": "The server turns the named resolution into claim ids and calls the review endpoint, which publishes an immutable version v+1. Supply `expectedVersion` from the decision list; a mismatch is refused with KNOWLEDGE_VERSION_CONFLICT rather than silently overwriting a decision someone else made in between. `Idempotency-Key` becomes the review's `reviewId`, so a retry is the same review, not a second one.\n\n**Scope:** `projects:write`.\n\n**Project capability:** `chat.write` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `KNOWLEDGE_DECISION_NOT_FOUND`, `KNOWLEDGE_RESOLUTION_NOT_ALLOWED`, `KNOWLEDGE_VERSION_CONFLICT`.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "postV1ProjectsProjectIdKnowledgeDecisionsDecisionIdResolve",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "decisionId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "resolution": {
                    "description": "confirm | reject | correct | keep_option | merge."
                  },
                  "value": {
                    "description": "The corrected value, for `correct`."
                  },
                  "optionId": {
                    "description": "The claim to keep, for `keep_option`."
                  },
                  "mergeWith": {
                    "description": "The entity to merge into, for `merge`."
                  },
                  "canonicalLabel": {
                    "description": "Optional label to canonicalize an entity under."
                  },
                  "reason": {
                    "description": "Optional free-text rationale, stored on the review."
                  },
                  "expectedVersion": {
                    "description": "The version the decision was read at."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Resolve one decision"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/reviews": {
      "post": {
        "summary": "Submit a batch of decisions (the raw primitive)",
        "description": "The underlying compare-and-set writer, for callers that have already assembled claim ids — typically after reading `/knowledge/decisions`. One batch publishes one version. Prefer `/decisions/:id/resolve` unless you are settling many decisions at once.\n\n**Scope:** `projects:write`.\n\n**Project capability:** `chat.write` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `KNOWLEDGE_VERSION_CONFLICT`.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "postV1ProjectsProjectIdKnowledgeReviews",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "description": "The version every decision was read at."
                  },
                  "decisions": {
                    "description": "Array of `{action, claimIds, correctedValue?, selectedClaimId?, canonicalLabel?, reason?}`."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Submit a batch of decisions (the raw primitive)"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "get": {
        "summary": "The review audit trail",
        "description": "Who decided what, and which version each review produced.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeReviews",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The review audit trail"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/reviews/{reviewId}": {
      "get": {
        "summary": "One review record",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeReviewsReviewId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "reviewId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One review record"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/suggestions": {
      "post": {
        "summary": "Ask the model to suggest resolutions",
        "description": "A paid model call. It **never publishes** — it returns proposed resolutions for a human or an agent to accept, which then go through the review endpoint like any other decision.\n\n**Scope:** `projects:generate`.\n\n**Project capability:** `asset.materialize` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "postV1ProjectsProjectIdKnowledgeSuggestions",
        "security": [
          {
            "apiKey": [
              "projects:generate"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expectedVersion": {
                    "description": "The version to suggest against."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Ask the model to suggest resolutions"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/knowledge/identities": {
      "get": {
        "summary": "The identity review queue",
        "description": "Single-name identities, possible duplicates and partial identities, with merge candidates. The UI only ever asks for `stakeholder`; `process` and `external_system` are exposed here too.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Knowledge"
        ],
        "operationId": "getV1ProjectsProjectIdKnowledgeIdentities",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "stakeholder (default), process, external_system.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "level",
            "in": "query",
            "required": false,
            "description": "required, follow_up, informational.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The identity review queue"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/chats": {
      "get": {
        "summary": "Chats in a project, most recently updated first",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Chat"
        ],
        "operationId": "getV1ProjectsProjectIdChats",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "active or archived.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Chats in a project, most recently updated first"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "post": {
        "summary": "Start a chat",
        "description": "**Scope:** `projects:write`.\n\n**Project capability:** `chat.write` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Chat"
        ],
        "operationId": "postV1ProjectsProjectIdChats",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Start a chat"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/chats/{chatId}": {
      "get": {
        "summary": "One chat",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Chat"
        ],
        "operationId": "getV1ProjectsProjectIdChatsChatId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chatId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One chat"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "patch": {
        "summary": "Rename or archive a chat",
        "description": "**Scope:** `projects:write`.\n\n**Project capability:** `chat.write` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Chat"
        ],
        "operationId": "patchV1ProjectsProjectIdChatsChatId",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chatId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Rename or archive a chat"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/chats/{chatId}/messages": {
      "get": {
        "summary": "Messages in a chat, oldest first, including cards",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Chat"
        ],
        "operationId": "getV1ProjectsProjectIdChatsChatIdMessages",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chatId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "description": "Only messages created before this ISO time.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Messages in a chat, oldest first, including cards"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      },
      "post": {
        "summary": "Send a chat turn",
        "description": "With `Accept: text/event-stream` the agent stream is passed through. Otherwise the call blocks until the turn settles and returns the persisted messages **including their cards**, which the stream does not carry. Cards are acted on with POST .../act.\n\n**Scope:** `projects:chat`.\n\n**Project capability:** `chat.send` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Chat"
        ],
        "operationId": "postV1ProjectsProjectIdChatsChatIdMessages",
        "security": [
          {
            "apiKey": [
              "projects:chat"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chatId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "text": {
                    "description": "The message."
                  },
                  "anchorAssetId": {
                    "description": "Optional. Anchors the turn to one asset, as opening it in the panel would."
                  },
                  "documentIds": {
                    "description": "Optional. Documents to attach to the turn."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Send a chat turn"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/chats/{chatId}/act": {
      "post": {
        "summary": "Act on a card: approve, decline or answer",
        "description": "The only way a chat reaches HubSpot. Approving a plan builds; approving a deploy card deploys exactly its snapshot; approving a fix card repairs and redeploys; approving a retire card removes with the typed confirmation. Answering a questions card returns `followUp`, which the caller posts as the next message so Jetty continues. requestId makes a retry return the first answer.\n\n**Scope:** `projects:write`.\n\n**Project capability:** `chat.write` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Chat"
        ],
        "operationId": "postV1ProjectsProjectIdChatsChatIdAct",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chatId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Act on a card: approve, decline or answer"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/portal-data": {
      "get": {
        "summary": "Portal data lanes: API scan, extension scan, relationships",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Portal"
        ],
        "operationId": "getV1ProjectsProjectIdPortalData",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Portal data lanes: API scan, extension scan, relationships"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/blueprint": {
      "get": {
        "summary": "The plan of record, with its lifecycle state",
        "description": "`lifecycle` is the same five-state derivation the Blueprint card renders. `canDerive` says in advance whether `POST /blueprint/derive` would do anything, and why not — a derivation needs a bound portal and published Knowledge, and one is already in flight while `deriving`.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Blueprint"
        ],
        "operationId": "getV1ProjectsProjectIdBlueprint",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The plan of record, with its lifecycle state"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/blueprint/versions": {
      "get": {
        "summary": "Blueprint version history, newest first",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Blueprint"
        ],
        "operationId": "getV1ProjectsProjectIdBlueprintVersions",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Blueprint version history, newest first"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/blueprint/versions/{version}": {
      "get": {
        "summary": "One Blueprint version",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Blueprint"
        ],
        "operationId": "getV1ProjectsProjectIdBlueprintVersionsVersion",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One Blueprint version"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/blueprint/derive": {
      "post": {
        "summary": "Derive a new Blueprint from current Knowledge",
        "description": "Spends credits. A refusal that is not an error — derivation already in progress, no published Knowledge, no sources — comes back as `skipped: true` with a `code` and a `reason` rather than an HTTP error, because none of those are the caller's mistake. Read `canDerive` on the GET to avoid the round trip.\n\n**Scope:** `projects:generate`.\n\n**Project capability:** `asset.materialize` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `BLUEPRINT_NOT_DERIVABLE`, `INSUFFICIENT_PROJECT_CREDITS`.",
        "tags": [
          "Blueprint"
        ],
        "operationId": "postV1ProjectsProjectIdBlueprintDerive",
        "security": [
          {
            "apiKey": [
              "projects:generate"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "instruction": {
                    "description": "Optional steer, at most 4000 characters."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Derive a new Blueprint from current Knowledge"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/runs": {
      "get": {
        "summary": "Runs, newest first",
        "description": "**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Runs & receipts"
        ],
        "operationId": "getV1ProjectsProjectIdRuns",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "generation, deploy, retire.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "queued, running, waiting_on_extension, paused, succeeded, partial, failed.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "chatId",
            "in": "query",
            "required": false,
            "description": "Only runs started from one chat.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Runs, newest first"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/runs/{runId}": {
      "get": {
        "summary": "One run, in full",
        "description": "Counters, per-worker progress, the named rows that were refused, blocked or failed with their verbatim errors, warnings (including the critical unmaterialized-node warning), model spend, and the credit pause if the run stopped for one.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `RUN_NOT_FOUND`.",
        "tags": [
          "Runs & receipts"
        ],
        "operationId": "getV1ProjectsProjectIdRunsRunId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One run, in full"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/deploy-log": {
      "get": {
        "summary": "The deploy receipt trail",
        "description": "Run headers newest first, each with its attempt rows oldest-first, plus `orphanRows` — attempts whose run header is gone, surfaced rather than dropped, because an attempt is the receipt. Live runs are included with `live: true`; the UI synthesizes those client-side.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Runs & receipts"
        ],
        "operationId": "getV1ProjectsProjectIdDeployLog",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Run headers per page (max 50).",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The deploy receipt trail"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/deploy-log/runs/{runId}": {
      "get": {
        "summary": "One run's attempt rows",
        "description": "Every field of every row, including the ones the log table hides: `intent`, `replayable`, `repairable`, the reason text, who requested it and the full error envelope.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Runs & receipts"
        ],
        "operationId": "getV1ProjectsProjectIdDeployLogRunsRunId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "runId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One run's attempt rows"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/deploy-log/receipts/{taskId}/{fetchRequestId}": {
      "get": {
        "summary": "One extension-lane request receipt",
        "description": "The raw request and response recorded for one browser-extension deploy step.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Runs & receipts"
        ],
        "operationId": "getV1ProjectsProjectIdDeployLogReceiptsTaskIdFetchRequestId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fetchRequestId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One extension-lane request receipt"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets": {
      "get": {
        "summary": "The canvas",
        "description": "Each row carries its canvas state, verification evidence, deployability and whether its *spec* rather than the portal is what failed. `counts` describes the whole project, not the page — the UI caps its listener at 500 and under-counts past that; this reports `truncated: true` instead of lying.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssets",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "draft, live, drifted, failed, detached.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "type",
            "in": "query",
            "required": false,
            "description": "Asset type id, e.g. `workflow`.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Substring match on name, asset id or HubSpot id.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "`nextCursor` from the previous page.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Page size.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The canvas"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}": {
      "get": {
        "summary": "One asset, in full",
        "description": "The stored document plus the derived projection: spec state and version, portal state for the production binding, the complete `lastFailure` envelope (class, route, owner, retryability), non-fatal `lastWarnings` from the last accepted attempt, verification evidence and staleness, and the drift record.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `ASSET_NOT_FOUND`.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssetsAssetId",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "One asset, in full"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/spec": {
      "get": {
        "summary": "The asset's specification",
        "description": "The asset's current generated spec, including large specs stored separately. The response says where the spec was read from.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `ASSET_SPEC_NOT_FOUND`.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssetsAssetIdSpec",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The asset's specification"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/issues": {
      "get": {
        "summary": "Every validation issue on the current spec",
        "description": "The asset panel renders the first eight; this returns them all.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssetsAssetIdIssues",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Every validation issue on the current spec"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/description": {
      "get": {
        "summary": "The plain-language description of what this asset does",
        "description": "`ready`, `generating` or `unavailable`. Generated lazily on first ask.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssetsAssetIdDescription",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "The plain-language description of what this asset does"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/impact": {
      "get": {
        "summary": "What removing or detaching this asset would affect",
        "description": "Includes `precondition` — the reason a removal would be refused before it is attempted. The Remove dialog ignores this today and leaves Delete enabled for the server to refuse; an agent should read it first.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssetsAssetIdImpact",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "What removing or detaching this asset would affect"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/hubspot-link": {
      "get": {
        "summary": "A deep link to the object in HubSpot",
        "description": "Built from the portal binding and the asset type. The UI assembles this in the browser; an agent handing a link to a human needs the same one.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssetsAssetIdHubspotLink",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "A deep link to the object in HubSpot"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/verify": {
      "post": {
        "summary": "Read the object back from HubSpot",
        "description": "Returns the verification verdict, the field-level `diff` when one was produced, and the reason when a verdict could not be established. The UI never renders a fresh `diff`; it is here.\n\n**Scope:** `projects:write`.\n\n**Project capability:** `chat.write` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Assets"
        ],
        "operationId": "postV1ProjectsProjectIdAssetsAssetIdVerify",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Read the object back from HubSpot"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/repair": {
      "post": {
        "summary": "Repair the asset",
        "description": "Spends credits. When `reason` is omitted the server derives it from the asset's current state — the same construction the asset panel performs before calling this (`AssetDetail.tsx:334-345`), so a caller does not have to know the reason vocabulary to ask for the obvious repair.\n\n**Scope:** `projects:generate`.\n\n**Project capability:** `asset.repair` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.",
        "tags": [
          "Assets"
        ],
        "operationId": "postV1ProjectsProjectIdAssetsAssetIdRepair",
        "security": [
          {
            "apiKey": [
              "projects:generate"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reason": {
                    "description": "Optional `{kind, ...}`. Derived from the asset's state when omitted."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Repair the asset"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/restore": {
      "post": {
        "summary": "Restore our version over the portal's drift",
        "description": "\"Restore ours\" is a repair with `reason.kind = \"drift\"`: it re-applies the specification Jetstack holds, overwriting whatever changed in HubSpot. Refused when the extension lane is required and no browser session is available.\n\n**Scope:** `projects:generate`.\n\n**Project capability:** `asset.repair` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `ASSET_EXTENSION_REQUIRED`.",
        "tags": [
          "Assets"
        ],
        "operationId": "postV1ProjectsProjectIdAssetsAssetIdRestore",
        "security": [
          {
            "apiKey": [
              "projects:generate"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Restore our version over the portal's drift"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/repairs/{idempotencyKey}": {
      "get": {
        "summary": "A repair's review record",
        "description": "The durable projection of a repair: pending, settled, or missing. A settled repair is delivered through a deploy card in the chat.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssetsAssetIdRepairsIdempotencyKey",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "idempotencyKey",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "A repair's review record"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/setup-items": {
      "get": {
        "summary": "List the asset's setup items",
        "description": "The setup items the asset's current spec leaves for a person, each with its stable `id` (what the setup-item write takes) and, when a user marked it done for this spec, its attestation. Derived on the server from the stored spec, including one too large to inline.\n\n**Scope:** `projects:read`.\n\n**Project capability:** `project.read` — held by the key creator's role on this project.\n\n**Refusal codes:** `ASSET_NOT_FOUND`, `ASSET_SETUP_ITEM_STALE`.",
        "tags": [
          "Assets"
        ],
        "operationId": "getV1ProjectsProjectIdAssetsAssetIdSetupItems",
        "security": [
          {
            "apiKey": [
              "projects:read"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "List the asset's setup items"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/setup-items/{itemId}": {
      "post": {
        "summary": "Mark a setup item done, or undo it",
        "description": "Records (or withdraws) a user's attestation that one required setup item is done. `itemId` is the stable id of an item on the asset's current spec; an id from an older spec is refused with 409. The attestation is the user's word (`evidence: \"user_attested\"`), never a HubSpot check, and it stops counting when the spec changes.\n\n**Scope:** `projects:write`.\n\n**Project capability:** `asset.repair` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `ASSET_NOT_FOUND`, `ASSET_SETUP_ITEM_STALE`.",
        "tags": [
          "Assets"
        ],
        "operationId": "postV1ProjectsProjectIdAssetsAssetIdSetupItemsItemId",
        "security": [
          {
            "apiKey": [
              "projects:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "itemId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "done": {
                    "description": "`true` to mark the item done, `false` to undo."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Mark a setup item done, or undo it"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    },
    "/v1/projects/{projectId}/assets/{assetId}/retire": {
      "post": {
        "summary": "Discard, detach or remove an asset",
        "description": "`discard` drops a draft that was never deployed; `detach` stops tracking an object and leaves it untouched in HubSpot; `remove` **deletes it from the portal** and requires `confirmationName` to match the asset's name exactly. Refusals are specific: no binding, has a binding, an operation is in flight, not removable, confirmation required, precondition failed, extension offline, unaddressable.\n\n**Scope:** `projects:deploy`.\n\n**Project capability:** `asset.remove` — held by the key creator's role on this project.\n\nHonours `Idempotency-Key`; the key is also threaded into the operation's own identity, so a retry collapses inside the handler rather than only in the response cache.\n\n**Refusal codes:** `ASSET_NOT_REMOVABLE`, `ASSET_CONFIRMATION_REQUIRED`, `ASSET_PRECONDITION_FAILED`, `PROJECT_OPERATION_IN_FLIGHT`, `ASSET_EXTENSION_REQUIRED`.",
        "tags": [
          "Assets"
        ],
        "operationId": "postV1ProjectsProjectIdAssetsAssetIdRetire",
        "security": [
          {
            "apiKey": [
              "projects:deploy"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/InstanceId"
          },
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "assetId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scope": {
                    "description": "discard | detach | remove."
                  },
                  "confirmationName": {
                    "description": "Required for `remove` — the asset's exact name."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "description": "Discard, detach or remove an asset"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The key lacks the scope, or the key creator's project role lacks the capability. The body names which.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No such resource in this organization."
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Projects"
    },
    {
      "name": "Access"
    },
    {
      "name": "Members"
    },
    {
      "name": "Portal"
    },
    {
      "name": "Documents"
    },
    {
      "name": "Knowledge"
    },
    {
      "name": "Chat"
    },
    {
      "name": "Blueprint"
    },
    {
      "name": "Assets"
    },
    {
      "name": "Runs & receipts"
    },
    {
      "name": "Credits"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ]
}
