{"openapi":"3.1.0","info":{"title":"QuiltLab Public Agent API","version":"1.0.0","description":"Thin, intentional HTTP surface for agents and third-party connectors. Covers projects, quilts, blocks, the shared fabric catalog, and supply guides. Admin, billing, and internal Convex paths are unpublished. The same operations are exposed as MCP tools at /mcp (issue #289).","contact":{"url":"https://www.quiltlab.co/developers"}},"servers":[{"url":"https://www.quiltlab.co","description":"This deployment"},{"url":"https://www.quiltlab.co","description":"Production"}],"tags":[{"name":"Auth","description":"Integration authentication probe"},{"name":"Projects","description":"Caller-owned projects"},{"name":"Quilts","description":"Caller-owned quilts"},{"name":"Blocks","description":"Caller-owned blocks"},{"name":"Fabrics","description":"Shared system fabric catalog"},{"name":"Supplies","description":"Static quilting-supply guides"},{"name":"Assets","description":"Generic list/get across blocks, quilts, swatches, patterns"}],"paths":{"/api/v1/auth/me":{"get":{"operationId":"getAuthMe","tags":["Auth"],"summary":"Confirm integration authentication","description":"Return whether the request carried a valid Clerk OAuth access token or session, and the caller's Clerk user id. Does not return email or other profile fields. Use this to verify tokens before calling design operations.","security":[{"bearerAuth":[]}],"x-mcp-tool":null,"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"authenticated":{"type":"boolean"},"userId":{"type":"string"}},"required":["authenticated"],"additionalProperties":false}}},"example":{"success":true,"data":{"authenticated":true,"userId":"user_abc123"}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/fabrics":{"get":{"operationId":"searchFabricCatalog","tags":["Fabrics"],"summary":"Search the shared fabric catalog","description":"Search the QuiltLab system fabric catalog by fabric name, manufacturer, or collection. Returns up to 25 matching fabrics, each with manufacturer, collection, SKU, color, and a link to that collection in the QuiltLab fabric library. Searches only the shared system catalog, not a user's own saved fabrics. Anonymous. Maps to MCP tool search_fabric_catalog.","security":[],"x-mcp-tool":"search_fabric_catalog","parameters":[{"name":"query","in":"query","required":false,"schema":{"description":"Free text matched against fabric name, collection, or manufacturer.","type":"string","minLength":1,"maxLength":100},"description":"Free text matched against fabric name, collection, or manufacturer."},{"name":"manufacturer","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"collection","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":120}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Page cursor from a previous call with the SAME filters. Changing query, manufacturer or collection requires starting again with no cursor.","type":"string","maxLength":4096},"description":"Page cursor from a previous call with the SAME filters. Changing query, manufacturer or collection requires starting again with no cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"fabrics":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"manufacturer":{"type":"string"},"collection":{"type":"string"},"sku":{"type":"string"},"colorHex":{"type":"string"},"thumbnailUrl":{"type":"string"},"libraryUrl":{"type":"string"}},"required":["id","name","manufacturer","collection","libraryUrl"],"additionalProperties":false}},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"truncated":{"type":"boolean"},"libraryUrl":{"type":"string"}},"required":["fabrics","cursor","truncated","libraryUrl"],"additionalProperties":false}}},"example":{"success":true,"data":{"fabrics":[{"id":"sw_1","name":"Indigo Crossweave","manufacturer":"Example Mills","collection":"Indigo","libraryUrl":"https://www.quiltlab.co/library/swatches?manufacturer=Example+Mills"}],"cursor":null,"truncated":false,"libraryUrl":"https://www.quiltlab.co/library/swatches"}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/supplies":{"get":{"operationId":"browseSupplies","tags":["Supplies"],"summary":"Browse a quilting-supply guide","description":"Look up entries from one QuiltLab quilting-supply reference guide. Choose exactly one category per call. Each entry returns a name, a short summary, and a link to its QuiltLab guide page. Fabric-brand entries also carry third-party shop links. Maps to MCP tool browse_supplies.","security":[],"x-mcp-tool":"browse_supplies","parameters":[{"name":"category","in":"query","required":true,"schema":{"type":"string","enum":["fabric-brands","fabric-types","batting-materials","batting-brands","precuts","rotary-cutters","rulers","cutting-mats","quilting-machines","machine-brands"]}},{"name":"query","in":"query","required":false,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"category":{"type":"string","enum":["fabric-brands","fabric-types","batting-materials","batting-brands","precuts","rotary-cutters","rulers","cutting-mats","quilting-machines","machine-brands"]},"items":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"summary":{"type":"string"},"bestFor":{"type":"string"},"priceRange":{"type":"string"},"guideUrl":{"type":"string"},"retailers":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false}}},"required":["slug","name","summary","guideUrl"],"additionalProperties":false}},"totalMatching":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"truncated":{"type":"boolean"}},"required":["category","items","totalMatching","truncated"],"additionalProperties":false}}},"example":{"success":true,"data":{"category":"fabric-brands","items":[{"slug":"example-mills","name":"Example Mills","summary":"Cotton prints for piecing.","guideUrl":"https://www.quiltlab.co/quilting-fabrics/brands/example-mills"}],"totalMatching":1,"truncated":false}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/projects":{"get":{"operationId":"listProjects","tags":["Projects"],"summary":"List the caller's projects","description":"List QuiltLab projects the signed-in user owns or is a member of. Each project returns its name and a link that opens it on quiltlab.co. Returns no information about other people on a project. Maps to MCP tool list_my_projects.","security":[{"bearerAuth":[]}],"x-mcp-tool":"list_my_projects","parameters":[{"name":"query","in":"query","required":false,"schema":{"description":"Free text matched against the resource name.","type":"string","minLength":1,"maxLength":100},"description":"Free text matched against the resource name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Page cursor from a previous call with the SAME filters. Changing filters requires starting again with no cursor.","type":"string","maxLength":4096},"description":"Page cursor from a previous call with the SAME filters. Changing filters requires starting again with no cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"archived":{"type":"boolean"}},"required":["id","name","url"],"additionalProperties":false}},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"truncated":{"type":"boolean"},"projectsUrl":{"type":"string"}},"required":["projects","cursor","truncated","projectsUrl"],"additionalProperties":false}}},"example":{"success":true,"data":{"projects":[{"id":"proj_1","name":"Summer throw","url":"https://www.quiltlab.co/project/proj_1"}],"cursor":null,"truncated":false,"projectsUrl":"https://www.quiltlab.co/projects"}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"operationId":"createProject","tags":["Projects"],"summary":"Create an empty project","description":"Create one new, empty QuiltLab project owned by the signed-in user, from a name and an optional description, and return a link that opens it on quiltlab.co. The new project contains no blocks, quilts, or fabrics. Maps to MCP tool create_project. Creates are not replay-safe; do not retry blindly.","security":[{"bearerAuth":[]}],"x-mcp-tool":"create_project","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Reserved. Creates are not replay-safe in v1; clients should not retry blindly."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Short name for the new project.","type":"string","minLength":1,"maxLength":120},"description":{"type":"string","maxLength":1000}},"required":["name"]},"example":{"name":"Summer throw","description":"Picnic quilt"}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"projectId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"projectsUrl":{"type":"string"}},"required":["projectId","name","url","projectsUrl"],"additionalProperties":false}}},"example":{"success":true,"data":{"projectId":"proj_1","name":"Summer throw","url":"https://www.quiltlab.co/project/proj_1","projectsUrl":"https://www.quiltlab.co/projects"}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/assets":{"get":{"operationId":"listAssets","tags":["Assets"],"summary":"List saved items of one type","description":"List the signed-in user's own saved items of one type: quilt blocks, quilts, fabric swatches, or patterns. Choose exactly one type per call. Each item returns its name, dimensions, and a link that opens it in the matching QuiltLab editor. Maps to MCP tool list_my_assets.","security":[{"bearerAuth":[]}],"x-mcp-tool":"list_my_assets","parameters":[{"name":"resource","in":"query","required":true,"schema":{"type":"string","enum":["blocks","quilts","swatches","patterns"]}},{"name":"projectId","in":"query","required":false,"schema":{"description":"Limit the list to one project the caller belongs to.","type":"string","minLength":1,"maxLength":100},"description":"Limit the list to one project the caller belongs to."},{"name":"query","in":"query","required":false,"schema":{"description":"Free text matched against the resource name.","type":"string","minLength":1,"maxLength":100},"description":"Free text matched against the resource name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Page cursor from a previous call with the SAME filters. Changing filters requires starting again with no cursor.","type":"string","maxLength":4096},"description":"Page cursor from a previous call with the SAME filters. Changing filters requires starting again with no cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"resource":{"type":"string","enum":["blocks","quilts","swatches","patterns"]},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"gridRows":{"type":"number"},"gridCols":{"type":"number"},"blockSize":{"type":"number"},"shapeCount":{"type":"number"},"projectId":{"type":"string"},"colorHex":{"type":"string"},"layoutMode":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"}},"required":["id","name","url"],"additionalProperties":false}},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["resource","assets","cursor","truncated"],"additionalProperties":false}}},"example":{"success":true,"data":{"resource":"quilts","assets":[{"id":"quilt_1","name":"Nine-patch sampler","url":"https://www.quiltlab.co/quilt-editor/quilt_1"}],"cursor":null,"truncated":false}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/assets/{resource}/{id}":{"get":{"operationId":"getAsset","tags":["Assets"],"summary":"Read one saved item","description":"Read one saved quilt block, quilt, fabric swatch, or pattern belonging to the signed-in user. Returns the item's name, description, dimensions, and an editor link. Setting includeGeometry adds a size-bounded, reference-only outline of the piece layout. Maps to MCP tool get_asset.","security":[{"bearerAuth":[]}],"x-mcp-tool":"get_asset","parameters":[{"name":"resource","in":"path","required":true,"schema":{"type":"string","enum":["blocks","quilts","swatches","patterns"]}},{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"includeGeometry","in":"query","required":false,"schema":{"description":"Include a bounded, reference-only outline of the piece geometry. Media and long text are omitted.","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"description":"Include a bounded, reference-only outline of the piece geometry. Media and long text are omitted."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"resource":{"type":"string","enum":["blocks","quilts","swatches","patterns"]},"asset":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"gridRows":{"type":"number"},"gridCols":{"type":"number"},"blockSize":{"type":"number"},"shapeCount":{"type":"number"},"projectId":{"type":"string"},"colorHex":{"type":"string"},"layoutMode":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"},"description":{"type":"string"},"geometry":{},"geometryStatus":{"type":"string"}},"required":["id","name","url"],"additionalProperties":false},"url":{"type":"string"},"untrustedContent":{"type":"boolean"}},"required":["resource","asset","url","untrustedContent"],"additionalProperties":false}}},"example":{"success":true,"data":{"resource":"blocks","asset":{"id":"blk_1","name":"Half-square","url":"https://www.quiltlab.co/block-editor/blk_1"},"url":"https://www.quiltlab.co/block-editor/blk_1","untrustedContent":true}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/quilts":{"get":{"operationId":"listQuilts","tags":["Quilts"],"summary":"List the caller's quilts","description":"Convenience alias for listAssets with resource=quilts. Same MCP tool (list_my_assets) and the same ownership rules.","security":[{"bearerAuth":[]}],"x-mcp-tool":"list_my_assets","parameters":[{"name":"projectId","in":"query","required":false,"schema":{"description":"Limit the list to one project the caller belongs to.","type":"string","minLength":1,"maxLength":100},"description":"Limit the list to one project the caller belongs to."},{"name":"query","in":"query","required":false,"schema":{"description":"Free text matched against the resource name.","type":"string","minLength":1,"maxLength":100},"description":"Free text matched against the resource name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Page cursor from a previous call with the SAME filters. Changing filters requires starting again with no cursor.","type":"string","maxLength":4096},"description":"Page cursor from a previous call with the SAME filters. Changing filters requires starting again with no cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"resource":{"type":"string","enum":["blocks","quilts","swatches","patterns"]},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"gridRows":{"type":"number"},"gridCols":{"type":"number"},"blockSize":{"type":"number"},"shapeCount":{"type":"number"},"projectId":{"type":"string"},"colorHex":{"type":"string"},"layoutMode":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"}},"required":["id","name","url"],"additionalProperties":false}},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["resource","assets","cursor","truncated"],"additionalProperties":false}}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/quilts/{id}":{"get":{"operationId":"getQuilt","tags":["Quilts"],"summary":"Read one quilt","description":"Convenience alias for getAsset with resource=quilts. Maps to MCP tool get_asset.","security":[{"bearerAuth":[]}],"x-mcp-tool":"get_asset","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"includeGeometry","in":"query","required":false,"schema":{"description":"Include a bounded, reference-only outline of the piece geometry. Media and long text are omitted.","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"description":"Include a bounded, reference-only outline of the piece geometry. Media and long text are omitted."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"resource":{"type":"string","enum":["blocks","quilts","swatches","patterns"]},"asset":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"gridRows":{"type":"number"},"gridCols":{"type":"number"},"blockSize":{"type":"number"},"shapeCount":{"type":"number"},"projectId":{"type":"string"},"colorHex":{"type":"string"},"layoutMode":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"},"description":{"type":"string"},"geometry":{},"geometryStatus":{"type":"string"}},"required":["id","name","url"],"additionalProperties":false},"url":{"type":"string"},"untrustedContent":{"type":"boolean"}},"required":["resource","asset","url","untrustedContent"],"additionalProperties":false}}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/blocks":{"get":{"operationId":"listBlocks","tags":["Blocks"],"summary":"List the caller's blocks","description":"Convenience alias for listAssets with resource=blocks. Maps to MCP tool list_my_assets.","security":[{"bearerAuth":[]}],"x-mcp-tool":"list_my_assets","parameters":[{"name":"projectId","in":"query","required":false,"schema":{"description":"Limit the list to one project the caller belongs to.","type":"string","minLength":1,"maxLength":100},"description":"Limit the list to one project the caller belongs to."},{"name":"query","in":"query","required":false,"schema":{"description":"Free text matched against the resource name.","type":"string","minLength":1,"maxLength":100},"description":"Free text matched against the resource name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50}},{"name":"cursor","in":"query","required":false,"schema":{"description":"Page cursor from a previous call with the SAME filters. Changing filters requires starting again with no cursor.","type":"string","maxLength":4096},"description":"Page cursor from a previous call with the SAME filters. Changing filters requires starting again with no cursor."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"resource":{"type":"string","enum":["blocks","quilts","swatches","patterns"]},"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"gridRows":{"type":"number"},"gridCols":{"type":"number"},"blockSize":{"type":"number"},"shapeCount":{"type":"number"},"projectId":{"type":"string"},"colorHex":{"type":"string"},"layoutMode":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"}},"required":["id","name","url"],"additionalProperties":false}},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}]},"truncated":{"type":"boolean"}},"required":["resource","assets","cursor","truncated"],"additionalProperties":false}}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}},"post":{"operationId":"createBlock","tags":["Blocks"],"summary":"Create an empty block stub","description":"Create one new, empty quilt block owned by the signed-in user, from a name and a finished width and height in inches, and return a link that opens it in the QuiltLab Block Editor. The block is created with no pieces in it. Maps to MCP tool create_block_stub. Creates are not replay-safe; do not retry blindly.","security":[{"bearerAuth":[]}],"x-mcp-tool":"create_block_stub","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Reserved. Creates are not replay-safe in v1; clients should not retry blindly."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"description":"Name for the new block.","type":"string","minLength":1,"maxLength":120},"finishedWidthInches":{"description":"Finished block width in inches, before seam allowances.","type":"number","minimum":0.25,"maximum":240},"finishedHeightInches":{"description":"Finished block height in inches, before seam allowances.","type":"number","minimum":0.25,"maximum":240}},"required":["name","finishedWidthInches","finishedHeightInches"]},"example":{"name":"Half-square","finishedWidthInches":12,"finishedHeightInches":12}}}},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"blockId":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"finishedWidthInches":{"type":"number"},"finishedHeightInches":{"type":"number"}},"required":["blockId","name","url","finishedWidthInches","finishedHeightInches"],"additionalProperties":false}}},"example":{"success":true,"data":{"blockId":"blk_1","name":"Half-square","url":"https://www.quiltlab.co/block-editor/blk_1","finishedWidthInches":12,"finishedHeightInches":12}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}},"/api/v1/blocks/{id}":{"get":{"operationId":"getBlock","tags":["Blocks"],"summary":"Read one block","description":"Convenience alias for getAsset with resource=blocks. Maps to MCP tool get_asset.","security":[{"bearerAuth":[]}],"x-mcp-tool":"get_asset","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","minLength":1,"maxLength":100}},{"name":"includeGeometry","in":"query","required":false,"schema":{"description":"Include a bounded, reference-only outline of the piece geometry. Media and long text are omitted.","anyOf":[{"type":"boolean"},{"type":"string","enum":["true","false"]}]},"description":"Include a bounded, reference-only outline of the piece geometry. Media and long text are omitted."}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","required":["success","data"],"properties":{"success":{"type":"boolean","enum":[true]},"data":{"type":"object","properties":{"resource":{"type":"string","enum":["blocks","quilts","swatches","patterns"]},"asset":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string"},"width":{"type":"number"},"height":{"type":"number"},"gridRows":{"type":"number"},"gridCols":{"type":"number"},"blockSize":{"type":"number"},"shapeCount":{"type":"number"},"projectId":{"type":"string"},"colorHex":{"type":"string"},"layoutMode":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"archived":{"type":"boolean"},"description":{"type":"string"},"geometry":{},"geometryStatus":{"type":"string"}},"required":["id","name","url"],"additionalProperties":false},"url":{"type":"string"},"untrustedContent":{"type":"boolean"}},"required":["resource","asset","url","untrustedContent"],"additionalProperties":false}}}}}},"400":{"description":"Invalid arguments","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"401":{"description":"Missing or invalid Clerk OAuth access token. WWW-Authenticate points at /.well-known/oauth-protected-resource.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}},"503":{"description":"Agent API disabled or catalog unavailable on this deployment","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryAfter":{"type":"number"}},"required":["code","message"],"additionalProperties":false}},"required":["success","error"],"additionalProperties":false}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Clerk OAuth 2.1 access token (the same token accepted at /mcp). Discover authorization_endpoint and token_endpoint from /.well-known/oauth-protected-resource → the Clerk RFC 8414 document. Do not POST tokens to /.well-known/oauth-authorization-server — that route is metadata only. Session cookies also work for browser clients."}}},"x-quiltlab":{"mcpUrl":"https://www.quiltlab.co/mcp","documentationUrl":"https://www.quiltlab.co/developers","llmsTxt":"https://www.quiltlab.co/llms.txt","arazzoUrl":"https://www.quiltlab.co/api/v1/arazzo.yaml"}}