{
  "openapi": "3.0.3",
  "info": {
    "title": "BoardRepo Integration API",
    "version": "1",
    "description": "Connect, Pull and Push for manually registered desktop, browser and backend integrations.\nContact hello@boardrepo.com for a client ID and reviewed callbacks/origins.\nUse authorization-code OAuth with S256 PKCE; backend clients also authenticate with a secret.\nDefault partner access expires after 30 days. Inspect expires_in and granted scope, and reconnect on expiry.\nThere are no refresh tokens or personal API keys in this release.\nThe change-request protocol additions describe the coordinated release candidate;\nproduction deployment and partner acceptance remain separate gates.\n\nPush sends a complete snapshot: omitted paths are removed. Pull an exact version first and\npreserve files your tool does not edit. A stale base is rejected, never silently overwritten.\nUse one stable idempotency key per logical save, persist the commit intent, and query its\noperation after a lost response. Cancelling a request does not prove publication was cancelled.\n\nSend bearer tokens only to BoardRepo, without session cookies. Upload ZIP bytes separately\nto the returned storage URL using exactly its signed headers, without the bearer token.\nBrowser origins must be registered for both API and object-storage CORS.\nNonempty unsupported formats retain files and history without previews or discovery eligibility.\nSee the HTTP guide for archive safeguards, quotas, integrity verification and runnable examples.\n",
    "contact": {
      "name": "BoardRepo integrations",
      "email": "hello@boardrepo.com"
    }
  },
  "servers": [
    {
      "url": "https://boardrepo.com",
      "description": "Production (registered integrations only)"
    }
  ],
  "externalDocs": {
    "description": "HTTP guide and runnable examples",
    "url": "https://boardrepo.com/docs/integrations/http.md"
  },
  "security": [
    {
      "userConnection": [
        "project:read"
      ]
    }
  ],
  "tags": [
    {
      "name": "Connection",
      "description": "User consent and bounded OAuth connections."
    },
    {
      "name": "Library",
      "description": "Live account permissions determine available boards and destinations."
    },
    {
      "name": "Pull",
      "description": "Exact published versions and original file bytes."
    },
    {
      "name": "Push",
      "description": "Prepare a complete ZIP, PUT it to storage, then commit the same intent."
    },
    {
      "name": "Recovery",
      "description": "Resolve interrupted saves without duplicating versions."
    },
    {
      "name": "Change requests",
      "description": "Reserve publication with one open change request, upload revisions from Sync and recover operations."
    },
    {
      "name": "Design reads",
      "description": "Read-only views of a board's design: schematic connectivity, PCB copper, file structure, text search, stored checks and version history. The same operations as the BoardRepo MCP tools of the same name."
    }
  ],
  "paths": {
    "/oauth/authorize": {
      "get": {
        "operationId": "authorizeConnection",
        "tags": [
          "Connection"
        ],
        "summary": "Open user sign-in and consent",
        "description": "Navigate the user's system browser to this URL. Signup preserves the consent destination.\nOn approval, the callback receives code, state and iss. On cancellation it receives\nerror=access_denied and state. Validate state and the callback URL before exchanging the\ncode; when present, iss must equal the BoardRepo origin. The user may narrow write access to read-only.\n",
        "security": [],
        "parameters": [
          {
            "name": "client_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "response_type",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "code"
              ]
            }
          },
          {
            "name": "redirect_uri",
            "in": "query",
            "required": true,
            "description": "Exact registered callback URL.",
            "schema": {
              "type": "string",
              "format": "uri",
              "maxLength": 2048
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": true,
            "description": "Cryptographically random value bound to the initiating session.",
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 2048
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "project:read",
                "project:read project:write"
              ]
            }
          },
          {
            "name": "resource",
            "in": "query",
            "required": true,
            "description": "The BoardRepo origin followed by /api/v1.",
            "schema": {
              "type": "string",
              "format": "uri"
            },
            "example": "https://boardrepo.com/api/v1"
          },
          {
            "name": "code_challenge",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{43}$"
            }
          },
          {
            "name": "code_challenge_method",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "S256"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "HTML consent or validation page."
          },
          "307": {
            "description": "Redirect to sign-in when needed."
          },
          "default": {
            "description": "HTML error or redirect; do not treat this browser navigation as a JSON API."
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "operationId": "exchangeAuthorizationCode",
        "tags": [
          "Connection"
        ],
        "summary": "Exchange a single-use code",
        "description": "Codes expire after five minutes. PKCE is required for every client type.\nDesktop/browser clients must not supply a client secret. Backend clients supply their secret\nin the form or with HTTP Basic (percent-encoded client ID and secret), never both.\nA failed or uncertain exchange may require restarting Connect.\n",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type",
                  "redirect_uri",
                  "code",
                  "code_verifier"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "authorization_code"
                    ]
                  },
                  "client_id": {
                    "type": "string",
                    "description": "Required unless supplied by HTTP Basic client authentication."
                  },
                  "redirect_uri": {
                    "type": "string",
                    "format": "uri"
                  },
                  "code": {
                    "type": "string"
                  },
                  "code_verifier": {
                    "type": "string",
                    "minLength": 43,
                    "maxLength": 128
                  },
                  "client_secret": {
                    "type": "string",
                    "description": "Backend clients only."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Store securely and honor the actual granted scope and lifetime.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "access_token",
                    "token_type",
                    "scope",
                    "expires_in"
                  ],
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "token_type": {
                      "type": "string",
                      "enum": [
                        "Bearer"
                      ]
                    },
                    "scope": {
                      "type": "string"
                    },
                    "expires_in": {
                      "type": "integer",
                      "minimum": 1,
                      "description": "Seconds until expiry."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/OAuthError"
          },
          "401": {
            "$ref": "#/components/responses/OAuthError"
          },
          "429": {
            "$ref": "#/components/responses/OAuthError"
          },
          "default": {
            "description": "Connection unavailable; retain the initiating state and restart Connect if necessary."
          }
        }
      }
    },
    "/oauth/revoke": {
      "post": {
        "operationId": "revokeConnection",
        "tags": [
          "Connection"
        ],
        "summary": "Disconnect a token",
        "description": "Unknown and already revoked partner tokens also return 200. Revocation blocks further access and commits, including prepared uploads.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revocation processed; empty response."
          },
          "429": {
            "description": "Retry after the indicated number of seconds; empty response.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "default": {
            "description": "Revocation unavailable."
          }
        }
      }
    },
    "/api/v1/me": {
      "get": {
        "operationId": "getCurrentAccount",
        "tags": [
          "Library"
        ],
        "summary": "Read the connected account and create destinations",
        "responses": {
          "200": {
            "description": "Use a permitted owner principal and its current uploadPolicy.hash when creating a board.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "user",
                    "ownerPrincipals"
                  ],
                  "properties": {
                    "user": {
                      "type": "object",
                      "required": [
                        "id",
                        "handle",
                        "email"
                      ],
                      "properties": {
                        "id": {
                          "$ref": "#/components/schemas/Uuid"
                        },
                        "handle": {
                          "type": "string",
                          "nullable": true
                        },
                        "email": {
                          "type": "string",
                          "nullable": true
                        }
                      }
                    },
                    "ownerPrincipals": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/OwnerPrincipal"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects": {
      "get": {
        "operationId": "listProjects",
        "tags": [
          "Library"
        ],
        "summary": "List the user's accessible library",
        "description": "Includes boards the account can access now. This is not public discovery. Live board permissions still apply.",
        "responses": {
          "200": {
            "description": "Accessible projects and exact current heads.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "projects"
                  ],
                  "properties": {
                    "projects": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Project"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      },
      "post": {
        "operationId": "createProject",
        "tags": [
          "Push"
        ],
        "summary": "Commit a prepared new project",
        "description": "PUT the exact archive to the prepared storage URL before committing. Repeat the same key,\nmessage, owner and policy from preparation. Personal boards start Unlisted and organization\nboards start Private. Publication authorization is rechecked at commit.\n",
        "security": [
          {
            "userConnection": [
              "project:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ArchiveProtocol"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCommit"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved project, including an idempotent replay of the same result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreatedProject"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "get": {
        "operationId": "getProject",
        "tags": [
          "Library"
        ],
        "summary": "Read a project and its current head",
        "responses": {
          "200": {
            "description": "Project envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Project"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/upload-policy": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "get": {
        "operationId": "getUploadPolicy",
        "tags": [
          "Push"
        ],
        "summary": "Read the current upload policy",
        "description": "Use the current hash in prepare and commit. The server remains the archive admission authority.",
        "responses": {
          "200": {
            "description": "Current policy fence.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UploadPolicy"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/versions/{versionId}/manifest": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        },
        {
          "name": "versionId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Uuid"
          }
        }
      ],
      "get": {
        "operationId": "getVersionManifest",
        "tags": [
          "Pull"
        ],
        "summary": "Read an exact published version",
        "description": "Pin versionId before downloading files. Verify byte lengths and SHA-256 hashes.\nmanifestDigest is SHA-256 of compact UTF-8 JSON containing [path,blobSha] pairs sorted by\nUTF-8 path bytes. Downloads stay coherent even when the project's head advances.\n",
        "responses": {
          "200": {
            "description": "Immutable version manifest with original paths and content hashes.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Manifest"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/blobs/{sha}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        },
        {
          "name": "sha",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/Sha256"
          }
        }
      ],
      "get": {
        "operationId": "downloadFile",
        "tags": [
          "Pull"
        ],
        "summary": "Download original file bytes",
        "description": "The hash must be referenced by this accessible project. Reauthorizes each request; use credentials omit in browsers.",
        "responses": {
          "200": {
            "description": "Original binary bytes; verify against the manifest before saving locally.",
            "headers": {
              "Content-Length": {
                "schema": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "Cache-Control": {
                "schema": {
                  "type": "string"
                },
                "example": "private, no-store"
              }
            },
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/uploads": {
      "post": {
        "operationId": "prepareProject",
        "tags": [
          "Push"
        ],
        "summary": "Prepare a new-project ZIP upload",
        "description": "Supply a nonempty complete project ZIP, in any admitted native format. The transport\noriginalFilename is always boardrepo-sync.zip; it does not rename files inside the archive.\nexpectedBytes and contentHash describe the exact ZIP bytes to PUT. New-project requests\nhave a 4096-byte JSON body limit. Organization ZIPs are limited to 250 MiB; personal ZIPs\nto 5 GiB, subject to account quotas and retained-file limits in the HTTP guide.\n",
        "security": [
          {
            "userConnection": [
              "project:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ArchiveProtocol"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUpload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/UploadPrepared"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/uploads": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "post": {
        "operationId": "prepareVersion",
        "tags": [
          "Push"
        ],
        "summary": "Prepare a complete replacement ZIP",
        "description": "expectedParentVersionId must be the version used to prepare this snapshot. A concurrent\nchange returns 409 head_moved. Every omitted path is removed when this snapshot commits.\nAn open change request returns 409 blocked_by_open_cr with its authorized reference.\nA refused idempotent retry after a lost stage response retires the existing live slot\nunder the project lock, retaining object charges until safe cleanup.\nBoth archive protocol 2 and change-request protocol 1 are required, even without an open request.\nThe JSON body is limited to 4096 bytes; ZIP and retained-file limits match project creation.\n",
        "security": [
          {
            "userConnection": [
              "project:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ArchiveProtocol"
          },
          {
            "$ref": "#/components/parameters/ChangeRequestProtocol"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VersionUpload"
              }
            }
          }
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/UploadPrepared"
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/versions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "post": {
        "operationId": "commitVersion",
        "tags": [
          "Push"
        ],
        "summary": "Commit the complete replacement snapshot",
        "description": "After PUT, repeat the prepared base version, key, message and policy exactly. The base and\nlive authorization are rechecked atomically. A stale base returns 409 head_moved; preserve\nthe proposed files, pull the new head, reconcile locally and start a new operation.\nAn open change request blocks new publication, including identical-content no-ops, with\n409 blocked_by_open_cr. Close or merge the request, reconcile any advanced head and start\na fresh Push/key; reviewer verdicts alone do not settle it. Completed replay stays successful.\nBoth protocol headers remain required on commit retries. A terminal CR refusal is\nreplayed while its upload row remains; after safe cleanup POST may return 404 not_found.\nGET /api/v1/operations/{key} retains the authoritative failure. Without a blocker,\nidentical snapshots can return noop=true. A saved version succeeds before previews finish.\n",
        "security": [
          {
            "userConnection": [
              "project:write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ArchiveProtocol"
          },
          {
            "$ref": "#/components/parameters/ChangeRequestProtocol"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VersionCommit"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Saved version or idempotent replay; preview readiness is separate.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SavedVersion"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/operations/{key}": {
      "get": {
        "operationId": "getOperation",
        "tags": [
          "Recovery"
        ],
        "summary": "Recover an interrupted save",
        "description": "Keys are isolated per integration and user and survive reconnecting. Unknown keys do not\ndisclose other integrations' work. A pending operation with retryCommit=true asks the\nclient to replay its persisted commit intent. Honor retryAfterMs. A committed result is\nfinal even when the original response was lost or the caller cancelled its request.\nA failed open-request refusal retains its code, authorized openChangeRequest reference,\nmessage and retryable=false. That key stays failed after the request is resolved; prepare\na fresh logical Push. Polling needs no change-request protocol header.\n",
        "parameters": [
          {
            "name": "key",
            "in": "path",
            "required": true,
            "description": "URL-encode the logical key as one path segment.",
            "schema": {
              "$ref": "#/components/schemas/OperationKey"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current operation state.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Operation"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/reviews/workflow": {
      "get": {
        "operationId": "getChangeWorkflow",
        "tags": [
          "Change requests"
        ],
        "summary": "Read the open change request and workflow capability",
        "description": "Organization projects only. Returns workflow.protocol \"1\" and whether new changes may start,\nthe published head, and activeChange (author, readiness in_progress or ready, revision,\nlifecycleVersion, baseVersionId, sourceState, canUpdate, canClose) or null. A failed read\nnever means that no change request is open. Personal projects answer 404.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current workflow status.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      },
      "post": {
        "operationId": "postChangeWorkflow",
        "tags": [
          "Change requests"
        ],
        "summary": "Start a change, upload a revision, mark it Ready or Close it",
        "description": "Requires X-BoardRepo-Review-Workflow-Protocol 1. JSON bodies carry action start, ready or\nclose with an operationKey (UUID) and the expected base version; ready and close also carry\nreviewId, expectedRevision and expectedLifecycleVersion. A revision upload is multipart:\noperation (JSON with action update, archiveMode sync_v2, archiveSha256, policyVersion and\npolicyHash) plus archive, and also requires X-BoardRepo-Upload-Archive-Protocol 2. Only Sync\nmay upload revisions; browsers receive 426 client_update_required. Reusing an operationKey\nwith different inputs returns 409 operation_conflict; replaying the same request returns the\noriginal receipt. Stale revisions or lifecycle versions return 409 revision_changed or\nlifecycle_changed. A second change request returns 409 CR_ALREADY_OPEN with openChangeRequest.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Accepted receipt: operationKey, reviewId, number, revision, lifecycleVersion, readiness, state, manifestHash and acceptedAt.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "202": {
            "description": "Accepted but still finishing; recover the operation before retrying.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/reviews/workflow/operations/{key}": {
      "get": {
        "operationId": "recoverChangeWorkflowOperation",
        "tags": [
          "Change requests"
        ],
        "summary": "Recover a change workflow operation after a lost response",
        "description": "Returns state unknown, pending, committed (with its receipt) or failed (with its typed refusal).\nRequires current authorization; it never resurrects a closed request.\n",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Operation state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      },
      "post": {
        "operationId": "cancelChangeWorkflowOperation",
        "tags": [
          "Change requests"
        ],
        "summary": "Cancel an unfinished operation",
        "description": "Send the exact saved operation body. Cancelling fences that identity before different work may start; accepted work stays retained.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Terminal operation state.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/tools/read_schematic": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "post": {
        "operationId": "readSchematic",
        "tags": [
          "Design reads"
        ],
        "summary": "Read schematic connectivity",
        "description": "Components and the nets that connect them, for the latest version or the saved version chosen with version. With no focus the result is a bounded overview (components and a net index); ref returns one component and its nets; net returns the pins on one net. Net names are the schematic's. Reads stored data only: when nets have not been extracted, the components come from the parts list and netsStatus says so.\n\nRead-only and safe to retry. The same operation as the BoardRepo MCP tool read_schematic.",
        "x-boardrepo-mcp-tool": "read_schematic",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "version": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 1
                      },
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64
                      }
                    ],
                    "description": "Which saved version to read: a version number (3 or \"v3\"), a versionId from list_board_versions, \"latest\", or a release tag such as \"rev-A\". Omit for the latest version. Results echo the version they read; pass its id back to stay on it."
                  },
                  "ref": {
                    "type": "string",
                    "description": "Optional. One reference designator (e.g. U1, J2): returns it plus the nets it connects to and the other pins on those nets. Prefer this over a full overview for a wiring or pin question. Provide at most one of ref or net."
                  },
                  "net": {
                    "type": "string",
                    "description": "Optional. One net name as the schematic spells it (e.g. GND, USB_DP; a hierarchical net is '/CC2', a KiCad auto-name 'Net-(U1-Pad3)'): returns the pins on it. PCB-style and leaf spellings are resolved when unambiguous. Prefer this for 'what is on net X'. Provide at most one of ref or net."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The operation's result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "found": {
                      "type": "boolean"
                    },
                    "matchStatus": {
                      "type": "string",
                      "enum": [
                        "not_found",
                        "unknown"
                      ]
                    },
                    "requestedRef": {
                      "type": "string"
                    },
                    "requestedNet": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    },
                    "source": {
                      "type": "string"
                    },
                    "componentCount": {
                      "type": "integer"
                    },
                    "netCount": {
                      "type": "integer"
                    },
                    "truncated": {
                      "type": "boolean"
                    },
                    "netsAvailable": {
                      "type": "boolean"
                    },
                    "note": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "version": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "number": {
                          "type": "integer"
                        },
                        "latest": {
                          "type": "boolean"
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "id",
                        "number",
                        "latest",
                        "tags"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "found"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/tools/read_pcb": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "post": {
        "operationId": "readPcb",
        "tags": [
          "Design reads"
        ],
        "summary": "Read PCB copper connectivity",
        "description": "The PCB copper graph in millimetres for the latest version or the saved version chosen with version. With no focus the result is a bounded overview (board size, layers, a net index with via counts and routed length); net returns that net's pads and vias; ref returns one footprint's pads; pcb picks one board of a multi-board project. Copper pours are not included. Reads stored data only.\n\nRead-only and safe to retry. The same operation as the BoardRepo MCP tool read_pcb.",
        "x-boardrepo-mcp-tool": "read_pcb",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "version": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 1
                      },
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64
                      }
                    ],
                    "description": "Which saved version to read: a version number (3 or \"v3\"), a versionId from list_board_versions, \"latest\", or a release tag such as \"rev-A\". Omit for the latest version. Results echo the version they read; pass its id back to stay on it."
                  },
                  "pcb": {
                    "type": "string",
                    "description": "Optional. One PCB inside this project: \"default\" or a slug from a previous overview (e.g. plate). This is NOT a BoardRepo board selector. Omit when the project has a single PCB."
                  },
                  "ref": {
                    "type": "string",
                    "description": "Optional. One footprint reference (e.g. U1): returns its pads with nets, layers and positions. Provide at most one of ref or net."
                  },
                  "net": {
                    "type": "string",
                    "description": "Optional. One copper net name (e.g. GND): returns its pads and vias (including drill and layer span) plus track count and routed length. Prefer this for 'how many vias on net X' or 'is this net's routing reasonable'."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The operation's result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "found": {
                      "type": "boolean",
                      "description": "False when the requested pcb, ref or net was not read."
                    },
                    "copperAvailable": {
                      "type": "boolean",
                      "description": "Whether the copper graph exists yet."
                    },
                    "copperStatus": {
                      "type": "string",
                      "enum": [
                        "computing",
                        "unavailable"
                      ],
                      "description": "Why copper is missing."
                    },
                    "matchStatus": {
                      "type": "string",
                      "enum": [
                        "not_found",
                        "unknown",
                        "ambiguous"
                      ],
                      "description": "Why a ref or net did not match."
                    },
                    "requestedPcb": {
                      "type": "string",
                      "description": "The pcb asked for."
                    },
                    "requestedRef": {
                      "type": "string",
                      "description": "The ref asked for."
                    },
                    "requestedNet": {
                      "type": "string",
                      "description": "The net asked for."
                    },
                    "message": {
                      "type": "string",
                      "description": "Why nothing was found."
                    },
                    "pcb": {
                      "type": "string",
                      "description": "Which PCB of the project was read."
                    },
                    "note": {
                      "type": "string",
                      "description": "A caveat to pass on."
                    },
                    "hint": {
                      "type": "string",
                      "description": "What to try next."
                    },
                    "url": {
                      "type": "string",
                      "description": "The board's boardrepo.com URL."
                    },
                    "version": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "number": {
                          "type": "integer"
                        },
                        "latest": {
                          "type": "boolean"
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "id",
                        "number",
                        "latest",
                        "tags"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "found"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/tools/get_checks": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "post": {
        "operationId": "getChecks",
        "tags": [
          "Design reads"
        ],
        "summary": "Read stored KiCad check results",
        "description": "The stored DRC and ERC results for the latest version or the saved version chosen with version, with exact counts per category and paged example violations, or a fab house's stored verdict with vendor. Never runs a check, and a check that has not run is reported as not run, never as passing.\n\nRead-only and safe to retry. The same operation as the BoardRepo MCP tool get_checks.",
        "x-boardrepo-mcp-tool": "get_checks",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "version": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 1
                      },
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64
                      }
                    ],
                    "description": "Which saved version to read: a version number (3 or \"v3\"), a versionId from list_board_versions, \"latest\", or a release tag such as \"rev-A\". Omit for the latest version. Results echo the version they read; pass its id back to stay on it."
                  },
                  "category": {
                    "type": "string",
                    "enum": [
                      "drc",
                      "unconnected",
                      "parity",
                      "erc"
                    ],
                    "description": "Optional: return only this category's violation details. Counts for every category are always returned regardless."
                  },
                  "cursor": {
                    "type": "string",
                    "description": "Opaque pagination cursor from a previous call; pass to fetch the next page of violations."
                  },
                  "vendor": {
                    "type": "string",
                    "description": "Optional fab house. Known ids: jlcpcb, pcbway, oshpark, multi-cb, eurocircuits, advanced-circuits, seeed, elecrow. A house name or one of that house's profile ids also resolves. Returns geometric checks against that fab's stored profile for this board instead of the board's own DRC/ERC."
                  },
                  "rules": {
                    "type": "object",
                    "additionalProperties": {
                      "type": "number"
                    },
                    "description": "Optional: YOUR OWN limits in millimetres, when no published fab profile fits - an in-house process, a tier a vendor does not publish, or a house rule tighter than any of them. Keys are the same limit names list_fab_profiles reports (trackWidthOuterMm, clearanceOuterMm, drillPlatedMinMm, annularMinMm and so on); values are millimetres. Mutually exclusive with vendor. The result is never stored as if a fab had published it."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The operation's result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ran": {
                      "type": "boolean"
                    },
                    "vendor": {
                      "type": "string"
                    },
                    "vendorLabel": {
                      "type": "string"
                    },
                    "errorCount": {
                      "type": "integer"
                    },
                    "warningCount": {
                      "type": "integer"
                    },
                    "violations": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "hasNextPage": {
                      "type": "boolean"
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    },
                    "note": {
                      "type": "string"
                    },
                    "version": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "number": {
                          "type": "integer"
                        },
                        "latest": {
                          "type": "boolean"
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "id",
                        "number",
                        "latest",
                        "tags"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "ran"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/tools/query_design": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "post": {
        "operationId": "queryDesign",
        "tags": [
          "Design reads"
        ],
        "summary": "Query a KiCad file as structure",
        "description": "Matching nodes of one KiCad file, selected by a path of node names from the root (for example kicad_pcb, layers), with a depth limit and a cursor for the next page. Use it for what the schematic and PCB reads do not carry: zones, stackup details, footprint properties.\n\nRead-only and safe to retry. The same operation as the BoardRepo MCP tool query_design.",
        "x-boardrepo-mcp-tool": "query_design",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "version": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 1
                      },
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64
                      }
                    ],
                    "description": "Which saved version to read: a version number (3 or \"v3\"), a versionId from list_board_versions, \"latest\", or a release tag such as \"rev-A\". Omit for the latest version. Results echo the version they read; pass its id back to stay on it."
                  },
                  "path": {
                    "type": "string",
                    "description": "The exact file path within the board, as returned by list_board_files. Do not guess."
                  },
                  "select": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "maxItems": 6,
                    "description": "Node names from the root downward, e.g. [\"kicad_pcb\",\"layers\"], [\"kicad_pcb\",\"footprint\"], [\"kicad_pcb\",\"via\"] or [\"kicad_pcb\",\"segment\"] for raw via and track nodes, [\"kicad_pcb\",\"zone\"], or [\"kicad_sch\",\"lib_symbols\",\"symbol\"]. The first entry is the file's root node."
                  },
                  "depth": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 5,
                    "description": "How many levels of children to expand (default 2, at most 5). Keep it at 3 or less on a .kicad_pcb: a deep expansion of a large board is a large response."
                  },
                  "cursor": {
                    "type": "string",
                    "description": "Opaque pagination cursor from a previous call; pass to fetch the next page of matches."
                  }
                },
                "required": [
                  "path",
                  "select"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The operation's result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "path": {
                      "type": "string"
                    },
                    "select": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "totalMatches": {
                      "type": "integer"
                    },
                    "matches": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {},
                        "additionalProperties": true
                      }
                    },
                    "hasNextPage": {
                      "type": "boolean"
                    },
                    "nextCursor": {
                      "type": "string",
                      "nullable": true
                    },
                    "note": {
                      "type": "string"
                    },
                    "version": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "number": {
                          "type": "integer"
                        },
                        "latest": {
                          "type": "boolean"
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "id",
                        "number",
                        "latest",
                        "tags"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "path",
                    "select",
                    "totalMatches",
                    "matches",
                    "hasNextPage",
                    "nextCursor"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/tools/search_board": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "post": {
        "operationId": "searchBoard",
        "tags": [
          "Design reads"
        ],
        "summary": "Search inside a board's files",
        "description": "Literal, case-insensitive matches of one string across the board's text files: the file, line number and matching line for each hit, optionally restricted to paths ending in path_suffix.\n\nRead-only and safe to retry. The same operation as the BoardRepo MCP tool search_board.",
        "x-boardrepo-mcp-tool": "search_board",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "version": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "minimum": 1
                      },
                      {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 64
                      }
                    ],
                    "description": "Which saved version to read: a version number (3 or \"v3\"), a versionId from list_board_versions, \"latest\", or a release tag such as \"rev-A\". Omit for the latest version. Results echo the version they read; pass its id back to stay on it."
                  },
                  "query": {
                    "type": "string",
                    "description": "The literal text to find, e.g. \"USB_DP\" or \"ATmega328\". Not a regular expression."
                  },
                  "path_suffix": {
                    "type": "string",
                    "description": "Optional. Only search files ending with this, e.g. \".kicad_sch\" or \".md\"."
                  },
                  "max_results": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100,
                    "description": "Optional cap on matches returned (default 100)."
                  }
                },
                "required": [
                  "query"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The operation's result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "query": {
                      "type": "string"
                    },
                    "matches": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "path": {
                            "type": "string"
                          },
                          "line": {
                            "type": "integer"
                          },
                          "text": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "path",
                          "line",
                          "text"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "filesScanned": {
                      "type": "integer"
                    },
                    "filesSkipped": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "filesTruncated": {
                      "type": "boolean"
                    },
                    "bytesTruncated": {
                      "type": "boolean"
                    },
                    "timeTruncated": {
                      "type": "boolean"
                    },
                    "hasMore": {
                      "type": "boolean"
                    },
                    "note": {
                      "type": "string"
                    },
                    "version": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "number": {
                          "type": "integer"
                        },
                        "latest": {
                          "type": "boolean"
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "id",
                        "number",
                        "latest",
                        "tags"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "required": [
                    "query",
                    "matches",
                    "filesScanned",
                    "filesSkipped",
                    "filesTruncated",
                    "bytesTruncated",
                    "hasMore"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    },
    "/api/v1/projects/{id}/tools/list_board_versions": {
      "parameters": [
        {
          "$ref": "#/components/parameters/ProjectId"
        }
      ],
      "post": {
        "operationId": "listBoardVersions",
        "tags": [
          "Design reads"
        ],
        "summary": "List a board's saved versions",
        "description": "Saved versions, newest number first, with versionId, number, whether it is the latest, message, author, date, file count, drawing readiness, whether checks ran and release tags. Page with beforeVersion set to the previous page's nextBeforeVersion; a version saved meanwhile never shifts a page. checksRan means checks ran, not that they passed.\n\nRead-only and safe to retry. The same operation as the BoardRepo MCP tool list_board_versions.",
        "x-boardrepo-mcp-tool": "list_board_versions",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "properties": {
                  "beforeVersion": {
                    "description": "Exclusive: list versions numbered below this. Pass the previous page's nextBeforeVersion.",
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 9007199254740991
                  },
                  "limit": {
                    "default": 25,
                    "description": "Versions per page, at most 100; 25 by default.",
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 100
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The operation's result.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "projectId": {
                      "type": "string"
                    },
                    "url": {
                      "type": "string"
                    },
                    "latest": {
                      "type": "object",
                      "properties": {
                        "versionId": {
                          "type": "string"
                        },
                        "number": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "versionId",
                        "number"
                      ],
                      "additionalProperties": false,
                      "nullable": true
                    },
                    "total": {
                      "type": "integer"
                    },
                    "versions": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "versionId": {
                            "type": "string"
                          },
                          "number": {
                            "type": "integer"
                          },
                          "latest": {
                            "type": "boolean"
                          },
                          "message": {
                            "type": "string"
                          },
                          "author": {
                            "type": "string",
                            "nullable": true
                          },
                          "createdAt": {
                            "type": "string"
                          },
                          "fileCount": {
                            "type": "integer"
                          },
                          "drawingsReady": {
                            "type": "boolean"
                          },
                          "checksRan": {
                            "type": "boolean"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            }
                          },
                          "url": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "versionId",
                          "number",
                          "latest",
                          "message",
                          "author",
                          "createdAt",
                          "fileCount",
                          "drawingsReady",
                          "checksRan",
                          "tags",
                          "url"
                        ],
                        "additionalProperties": true
                      }
                    },
                    "nextBeforeVersion": {
                      "type": "integer",
                      "nullable": true
                    }
                  },
                  "required": [
                    "projectId",
                    "url",
                    "latest",
                    "total",
                    "versions",
                    "nextBeforeVersion"
                  ],
                  "additionalProperties": true
                }
              }
            }
          },
          "default": {
            "$ref": "#/components/responses/ApiError"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "userConnection": {
        "type": "oauth2",
        "description": "Manually registered integration, explicit user consent and S256 PKCE. Read/write grants\ncover the user's accessible library, including future boards. Live account permissions\nstill apply. project:write does not imply project:read. Use your application's OAuth flow;\nthis reference does not exchange or store tokens.\n",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://boardrepo.com/oauth/authorize",
            "tokenUrl": "https://boardrepo.com/oauth/token",
            "scopes": {
              "project:read": "Read account identity, accessible projects, files and operation receipts.",
              "project:write": "Create projects and publish versions where the user has permission."
            }
          }
        }
      }
    },
    "parameters": {
      "ProjectId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "$ref": "#/components/schemas/Uuid"
        }
      },
      "ArchiveProtocol": {
        "name": "X-BoardRepo-Upload-Archive-Protocol",
        "in": "header",
        "required": true,
        "description": "Version 2 archive admission is required for prepare and commit. After any required change-request protocol check, missing or obsolete archive protocol returns 426.",
        "schema": {
          "type": "string",
          "enum": [
            "2"
          ]
        }
      },
      "ChangeRequestProtocol": {
        "name": "X-BoardRepo-Change-Request-Protocol",
        "in": "header",
        "required": true,
        "description": "Existing-project prepare and commit require version 1 even with no open request. Missing or unsupported proof returns 403 client_update_required before archive validation or body processing. Creation, reads and operation polling are exempt.",
        "schema": {
          "type": "string",
          "enum": [
            "1"
          ]
        }
      }
    },
    "responses": {
      "OAuthError": {
        "description": "OAuth error. Restart Connect for invalid_grant; check registration for invalid_client. A 429 may include Retry-After in seconds.",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "string"
                },
                "error_description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "ApiError": {
        "description": "400 invalid_request/invalid_content/content_mismatch/credential_detected: fix the input.\n401 invalid_token: reconnect. 403 insufficient_scope: request the required scope.\n403 client_update_required: support change-request protocol 1 for existing-project writes;\nretain credentials. 409 blocked_by_open_cr: open the authorized openChangeRequest URL,\nclose or merge the request, reconcile the head and prepare a fresh Push/key. Reviewer\nverdicts do not settle the request. Its code is BLOCKED_BY_OPEN_CR and retryable is false.\nMissing or inaccessible resources return 404. 409 head_moved: reconcile against currentHead;\npolicy_changed: read the current policy and prepare a new intent; idempotency_mismatch:\nrestore the original intent or choose a new key; in_progress: poll the operation.\n410 upload_expired/upload_used: query the operation before preparing again.\n413 request_too_large: reduce input. 426: use archive protocol 2.\nFor 429/503 or retryable=true, back off and retry the same intent/key.\n",
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer",
              "minimum": 1
            }
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UploadPrepared": {
        "description": "PUT the exact ZIP to url with all returned headers (including If-None-Match when present),\nwithout OAuth or cookie credentials. Complete the upload before expiresAt, then commit.\nStorage error responses belong to object storage, not the BoardRepo JSON error schema.\n",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PreparedUpload"
            }
          }
        }
      }
    },
    "schemas": {
      "Uuid": {
        "type": "string",
        "format": "uuid"
      },
      "Sha256": {
        "type": "string",
        "pattern": "^[0-9a-f]{64}$"
      },
      "OperationKey": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "pattern": "^(?!integration:)",
        "description": "Stable key for one logical save; never reuse for changed content or intent."
      },
      "Message": {
        "type": "string",
        "maxLength": 500
      },
      "OpenChangeRequest": {
        "type": "object",
        "required": [
          "id",
          "number",
          "url"
        ],
        "additionalProperties": false,
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "number": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Canonical review URL; access is still required."
          }
        }
      },
      "OwnerPrincipal": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "handle",
          "name",
          "capabilities"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "kind": {
            "type": "string",
            "enum": [
              "personal",
              "organization"
            ]
          },
          "handle": {
            "type": "string",
            "nullable": true
          },
          "name": {
            "type": "string",
            "nullable": true
          },
          "capabilities": {
            "type": "object",
            "required": [
              "canCreateProject"
            ],
            "properties": {
              "canCreateProject": {
                "type": "boolean"
              }
            }
          },
          "uploadPolicy": {
            "$ref": "#/components/schemas/UploadPolicy"
          }
        }
      },
      "UploadPolicy": {
        "type": "object",
        "required": [
          "version",
          "hash",
          "rules",
          "expiresAt"
        ],
        "properties": {
          "version": {
            "type": "integer"
          },
          "hash": {
            "$ref": "#/components/schemas/Sha256"
          },
          "rules": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Optional exclusion rules are not applied to complete Sync snapshots. Server admission remains authoritative."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          }
        }
      },
      "Project": {
        "type": "object",
        "required": [
          "id",
          "slug",
          "name",
          "owner",
          "capabilities",
          "headVersionId",
          "headParentVersionId",
          "versionNumber",
          "versionPublishedAt",
          "manifestDigest",
          "headContentHash",
          "exportStatus",
          "exportError"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/Uuid"
          },
          "slug": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "owner": {
            "type": "object",
            "required": [
              "kind",
              "handle",
              "name"
            ],
            "properties": {
              "kind": {
                "type": "string",
                "enum": [
                  "personal",
                  "organization"
                ]
              },
              "handle": {
                "type": "string",
                "nullable": true
              },
              "name": {
                "type": "string",
                "nullable": true
              }
            }
          },
          "capabilities": {
            "type": "object",
            "required": [
              "canRead",
              "canPublishVersion"
            ],
            "properties": {
              "canRead": {
                "type": "boolean"
              },
              "canPublishVersion": {
                "type": "boolean"
              }
            }
          },
          "headVersionId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "headParentVersionId": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "versionNumber": {
            "type": "integer",
            "nullable": true
          },
          "versionPublishedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": true
          },
          "manifestDigest": {
            "type": "string",
            "nullable": true
          },
          "headContentHash": {
            "type": "string",
            "nullable": true
          },
          "exportStatus": {
            "type": "string",
            "description": "Preview processing state; saving is independent of preview completion."
          },
          "exportError": {
            "type": "string",
            "nullable": true
          },
          "sourceFormat": {
            "type": "string",
            "description": "Optional format hint; use the exact-version manifest for preview eligibility."
          },
          "openChangeRequest": {
            "description": "Present only for authorized organization-board publishers or request submitters; null when no request is open. Publication rechecks the gate.",
            "oneOf": [
              {
                "$ref": "#/components/schemas/OpenChangeRequest"
              },
              {
                "type": "object",
                "nullable": true,
                "enum": [
                  null
                ]
              }
            ]
          }
        }
      },
      "Manifest": {
        "type": "object",
        "required": [
          "versionId",
          "versionNumber",
          "manifestDigest",
          "author",
          "createdAt",
          "message",
          "sourceFormat",
          "previewStatus",
          "integrationClientId",
          "files"
        ],
        "properties": {
          "versionId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "versionNumber": {
            "type": "integer"
          },
          "manifestDigest": {
            "$ref": "#/components/schemas/Sha256"
          },
          "author": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "message": {
            "type": "string"
          },
          "sourceFormat": {
            "type": "string",
            "nullable": true
          },
          "previewStatus": {
            "type": "string",
            "enum": [
              "supported",
              "not_applicable"
            ]
          },
          "integrationClientId": {
            "type": "string",
            "nullable": true
          },
          "files": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "path",
                "blobSha",
                "bytes"
              ],
              "properties": {
                "path": {
                  "type": "string",
                  "description": "Original relative path; validate before writing locally."
                },
                "blobSha": {
                  "$ref": "#/components/schemas/Sha256"
                },
                "bytes": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            }
          }
        }
      },
      "CreateUpload": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "expectedBytes",
          "contentHash",
          "name",
          "originalFilename",
          "ownerPrincipalId",
          "policyHash",
          "idempotencyKey",
          "message"
        ],
        "properties": {
          "expectedBytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5368709120
          },
          "contentHash": {
            "$ref": "#/components/schemas/Sha256"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160
          },
          "originalFilename": {
            "type": "string",
            "enum": [
              "boardrepo-sync.zip"
            ]
          },
          "ownerPrincipalId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "policyHash": {
            "$ref": "#/components/schemas/Sha256"
          },
          "idempotencyKey": {
            "$ref": "#/components/schemas/OperationKey"
          },
          "message": {
            "$ref": "#/components/schemas/Message"
          }
        }
      },
      "VersionUpload": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "expectedBytes",
          "contentHash",
          "policyHash",
          "idempotencyKey",
          "expectedParentVersionId",
          "message"
        ],
        "properties": {
          "expectedBytes": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5368709120
          },
          "contentHash": {
            "$ref": "#/components/schemas/Sha256"
          },
          "policyHash": {
            "$ref": "#/components/schemas/Sha256"
          },
          "idempotencyKey": {
            "$ref": "#/components/schemas/OperationKey"
          },
          "expectedParentVersionId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "message": {
            "$ref": "#/components/schemas/Message"
          }
        }
      },
      "CreateCommit": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "uploadId",
          "ownerPrincipalId",
          "idempotencyKey",
          "message",
          "policyHash"
        ],
        "properties": {
          "uploadId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "ownerPrincipalId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "idempotencyKey": {
            "$ref": "#/components/schemas/OperationKey"
          },
          "message": {
            "$ref": "#/components/schemas/Message"
          },
          "policyHash": {
            "$ref": "#/components/schemas/Sha256"
          }
        }
      },
      "VersionCommit": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "uploadId",
          "expectedParentVersionId",
          "idempotencyKey",
          "message",
          "policyHash"
        ],
        "properties": {
          "uploadId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "expectedParentVersionId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "idempotencyKey": {
            "$ref": "#/components/schemas/OperationKey"
          },
          "message": {
            "$ref": "#/components/schemas/Message"
          },
          "policyHash": {
            "$ref": "#/components/schemas/Sha256"
          }
        }
      },
      "PreparedUpload": {
        "type": "object",
        "required": [
          "uploadId",
          "url",
          "method",
          "headers",
          "expiresAt",
          "operationId"
        ],
        "properties": {
          "uploadId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "method": {
            "type": "string",
            "enum": [
              "PUT"
            ]
          },
          "headers": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "operationId": {
            "$ref": "#/components/schemas/OperationKey"
          }
        }
      },
      "CreatedProject": {
        "type": "object",
        "required": [
          "projectId",
          "slug",
          "versionId",
          "versionNumber",
          "manifestDigest",
          "operationId"
        ],
        "properties": {
          "projectId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "slug": {
            "type": "string"
          },
          "versionId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "versionNumber": {
            "type": "integer"
          },
          "manifestDigest": {
            "$ref": "#/components/schemas/Sha256"
          },
          "operationId": {
            "$ref": "#/components/schemas/OperationKey"
          }
        }
      },
      "SavedVersion": {
        "type": "object",
        "required": [
          "versionId",
          "versionNumber",
          "manifestDigest",
          "exportStatus",
          "noop",
          "operationId"
        ],
        "properties": {
          "versionId": {
            "$ref": "#/components/schemas/Uuid"
          },
          "versionNumber": {
            "type": "integer"
          },
          "manifestDigest": {
            "$ref": "#/components/schemas/Sha256"
          },
          "exportStatus": {
            "type": "string"
          },
          "noop": {
            "type": "boolean"
          },
          "operationId": {
            "$ref": "#/components/schemas/OperationKey"
          }
        }
      },
      "Operation": {
        "oneOf": [
          {
            "type": "object",
            "required": [
              "state"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "unknown"
                ]
              }
            }
          },
          {
            "type": "object",
            "required": [
              "state",
              "retryAfterMs"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "pending"
                ]
              },
              "reason": {
                "type": "string"
              },
              "retryAfterMs": {
                "type": "integer",
                "minimum": 0
              },
              "retryCommit": {
                "type": "boolean"
              }
            }
          },
          {
            "type": "object",
            "required": [
              "state",
              "reason",
              "terminal"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "failed"
                ]
              },
              "reason": {
                "type": "string"
              },
              "terminal": {
                "type": "boolean",
                "enum": [
                  true
                ]
              },
              "code": {
                "type": "string",
                "description": "BLOCKED_BY_OPEN_CR for an open-request publication refusal."
              },
              "openChangeRequest": {
                "$ref": "#/components/schemas/OpenChangeRequest"
              },
              "message": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean",
                "description": "False for a retained open-request refusal."
              }
            }
          },
          {
            "type": "object",
            "required": [
              "state",
              "projectId",
              "versionId",
              "manifestDigest",
              "noop"
            ],
            "properties": {
              "state": {
                "type": "string",
                "enum": [
                  "committed"
                ]
              },
              "projectId": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "versionId": {
                "type": "string",
                "format": "uuid",
                "nullable": true
              },
              "manifestDigest": {
                "type": "string",
                "nullable": true
              },
              "versionNumber": {
                "type": "integer"
              },
              "operationId": {
                "$ref": "#/components/schemas/OperationKey"
              },
              "slug": {
                "type": "string"
              },
              "exportStatus": {
                "type": "string"
              },
              "noop": {
                "type": "boolean"
              }
            }
          }
        ]
      },
      "Error": {
        "type": "object",
        "required": [
          "message",
          "reason"
        ],
        "properties": {
          "message": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          },
          "retryAfterMs": {
            "type": "integer",
            "minimum": 0
          },
          "currentHead": {
            "type": "string",
            "format": "uuid",
            "nullable": true
          },
          "currentPolicyHash": {
            "type": "string"
          },
          "code": {
            "type": "string",
            "description": "BLOCKED_BY_OPEN_CR for an open-request publication refusal."
          },
          "openChangeRequest": {
            "$ref": "#/components/schemas/OpenChangeRequest"
          }
        }
      }
    }
  }
}
