{
  "openapi": "3.1.0",
  "info": {
    "title": "Building3D Design API",
    "version": "1.0.0",
    "description": "Building Design only. Never bypass revision conflicts. Other studios in an existing workspace are preserved."
  },
  "servers": [
    {
      "url": "https://building3d.app"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "b3d_\u2026"
      }
    }
  },
  "paths": {
    "/api/design": {
      "get": {
        "summary": "List designs, or get one using id",
        "operationId": "readDesigns",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "projects",
                "validate"
              ],
              "default": "projects"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Missing, revoked, expired or invalid key"
          },
          "403": {
            "description": "Insufficient permissions"
          },
          "404": {
            "description": "Project not found in permitted scope"
          },
          "409": {
            "description": "Revision or idempotency conflict"
          },
          "422": {
            "description": "Invalid design; inspect error.issues"
          },
          "429": {
            "description": "Rate limited; Retry-After in seconds"
          }
        }
      },
      "post": {
        "summary": "Validate using action=validate, otherwise create a project",
        "operationId": "validateOrCreateDesign",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "projects",
                "validate"
              ],
              "default": "projects"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "description": "Required for create. Reuse the same value only for the same design, retained for 30 days.",
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{16,100}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Missing, revoked, expired or invalid key"
          },
          "403": {
            "description": "Insufficient permissions"
          },
          "404": {
            "description": "Project not found in permitted scope"
          },
          "409": {
            "description": "Revision or idempotency conflict"
          },
          "422": {
            "description": "Invalid design; inspect error.issues"
          },
          "429": {
            "description": "Rate limited; Retry-After in seconds"
          },
          "201": {
            "description": "Project created"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "design"
                ],
                "properties": {
                  "design": {
                    "$ref": "https://building3d.app/design-schema.json"
                  },
                  "revision": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Replace a project building using id and current revision",
        "operationId": "updateDesign",
        "parameters": [
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "action",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "projects",
                "validate"
              ],
              "default": "projects"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "401": {
            "description": "Missing, revoked, expired or invalid key"
          },
          "403": {
            "description": "Insufficient permissions"
          },
          "404": {
            "description": "Project not found in permitted scope"
          },
          "409": {
            "description": "Revision or idempotency conflict"
          },
          "422": {
            "description": "Invalid design; inspect error.issues"
          },
          "429": {
            "description": "Rate limited; Retry-After in seconds"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "design"
                ],
                "properties": {
                  "design": {
                    "$ref": "https://building3d.app/design-schema.json"
                  },
                  "revision": {
                    "type": "integer",
                    "minimum": 1
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}