Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

feat(api): generate a deterministic Postman collection from the public OpenAPI spec

nirholas5b7ebbf190ef
diff --git a/docs/api-reference.md b/docs/api-reference.md
index c731548b8..0e6acba52 100644
--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -6,7 +6,7 @@ Base URL: `https://three.ws/api`
> For the in-browser JavaScript API (the `<agent-3d>` element, `Viewer`, `Runtime`, `SceneController`, skills, memory), see [js-api.md](./js-api.md) and [web-component.md](./web-component.md). For the high-level npm SDK, see [sdk.md](./sdk.md).
-The full machine-readable schema lives at [`https://three.ws/.well-known/openapi.yaml`](https://three.ws/.well-known/openapi.yaml). x402 paid endpoints are listed at [`/.well-known/x402.json`](https://three.ws/.well-known/x402.json) and the MCP endpoint is at [`/api/mcp`](https://three.ws/api/mcp).
+The full machine-readable schema lives at [`https://three.ws/.well-known/openapi.yaml`](https://three.ws/.well-known/openapi.yaml), with a ready-to-import Postman collection generated from the same spec at [`https://three.ws/.well-known/postman-collection.json`](https://three.ws/.well-known/postman-collection.json) (`npm run build:postman-collection` regenerates it, `npm run check:postman-collection` fails the gate when it drifts from the spec). x402 paid endpoints are listed at [`/.well-known/x402.json`](https://three.ws/.well-known/x402.json) and the MCP endpoint is at [`/api/mcp`](https://three.ws/api/mcp).
---
diff --git a/package-lock.json b/package-lock.json
index 166d6364f..16171d9b0 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -269,6 +269,7 @@
"i18n-iso-countries": "^7.14.0",
"jsdom": "30.0.1",
"json5": "^2.2.3",
+ "openapi-to-postmanv2": "^6.4.0",
"playwright": "^1.63.0",
"prettier": "^3.9.8",
"puppeteer": "^25.10.0",
@@ -8417,6 +8418,21 @@
}
}
},
+ "node_modules/@exodus/schemasafe": {
+ "version": "1.3.0",
+ "resolved": "https://registry.npmjs.org/@exodus/schemasafe/-/schemasafe-1.3.0.tgz",
+ "integrity": "sha512-5Aap/GaRupgNx/feGBwLLTVv8OQFfv3pq2lPRzPg9R+IOBnDgghTGW7l7EuVXOvg5cc/xSAlRW8rBrjIC3Nvqw==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/@faker-js/faker": {
+ "version": "5.5.3",
+ "resolved": "https://registry.npmjs.org/@faker-js/faker/-/faker-5.5.3.tgz",
+ "integrity": "sha512-R11tGE6yIFwqpaIqcfkcg7AICXzFg14+5h5v0TfF/9+RMDL6jhzCy/pxHVOfbALGdtVYdt6JdR21tuxEgl34dw==",
+ "deprecated": "Please update to a newer version.",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/@fast-csv/format": {
"version": "4.3.5",
"resolved": "https://registry.npmjs.org/@fast-csv/format/-/format-4.3.5.tgz",
@@ -31160,6 +31176,21 @@
"url": "https://github.com/sponsors/epoberezkin"
}
},
+ "node_modules/ajv-draft-04": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/ajv-draft-04/-/ajv-draft-04-1.0.0.tgz",
+ "integrity": "sha512-mv00Te6nmYbRp5DCwclxtt7yV/joXJPGS7nM+97GdxvuttCOfgI3K4U25zboyeX0O+myI8ERluxQe5wljMmVIw==",
+ "dev": true,
+ "license": "MIT",
+ "peerDependencies": {
+ "ajv": "^8.5.0"
+ },
+ "peerDependenciesMeta": {
+ "ajv": {
+ "optional": true
+ }
+ }
+ },
"node_modules/ajv-formats": {
"version": "3.0.1",
"license": "MIT",
@@ -32904,6 +32935,13 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/call-me-maybe": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/call-me-maybe/-/call-me-maybe-1.0.2.tgz",
+ "integrity": "sha512-HpX65o1Hnr9HH25ojC1YGs7HCQLq0GCOibSaWER0eNpgJ/Z1MZv2mTc7+xh6WOPxbRVcmgbv4hGU+uSQ/2xFZQ==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/callsites": {
"version": "3.1.0",
"license": "MIT",
@@ -33017,6 +33055,16 @@
"node": "*"
}
},
+ "node_modules/charset": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/charset/-/charset-1.0.1.tgz",
+ "integrity": "sha512-6dVyOOYjpfFcL1Y4qChrAoQLRHvj2ziyhcm0QJlhOcAhykL/k1kTUPbeo+87MNRTRdk2OIIsIXbuF3x2wi5EXg==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=4.0.0"
+ }
+ },
"node_modules/chokidar": {
"version": "5.0.0",
"license": "MIT",
@@ -33441,6 +33489,29 @@
"node": ">= 0.6"
}
},
+ "node_modules/compute-gcd": {
+ "version": "1.2.1",
+ "resolved": "https://registry.npmjs.org/compute-gcd/-/compute-gcd-1.2.1.tgz",
+ "integrity": "sha512-TwMbxBNz0l71+8Sc4czv13h4kEqnchV9igQZBi6QUaz09dnz13juGnnaWWJTRsP3brxOoxeB4SA2WELLw1hCtg==",
+ "dev": true,
+ "dependencies": {
+ "validate.io-array": "^1.0.3",
+ "validate.io-function": "^1.0.2",
+ "validate.io-integer-array": "^1.0.0"
+ }
+ },
+ "node_modules/compute-lcm": {
+ "version": "1.1.2",
+ "resolved": "https://registry.npmjs.org/compute-lcm/-/compute-lcm-1.1.2.tgz",
+ "integrity": "sha512-OFNPdQAXnQhDSKioX8/XYT6sdUlXwpeMjfd6ApxMJfyZ4GxmLR1xvMERctlYhlHwIiz6CSpBc2+qYKjHGZw4TQ==",
+ "dev": true,
+ "dependencies": {
+ "compute-gcd": "^1.2.1",
+ "validate.io-array": "^1.0.3",
+ "validate.io-function": "^1.0.2",
+ "validate.io-integer-array": "^1.0.0"
+ }
+ },
"node_modules/concat-map": {
"version": "0.0.1",
"license": "MIT"
@@ -37186,6 +37257,16 @@
"node": ">= 6"
}
},
+ "node_modules/file-type": {
+ "version": "3.9.0",
+ "resolved": "https://registry.npmjs.org/file-type/-/file-type-3.9.0.tgz",
+ "integrity": "sha512-RLoqTXE8/vPmMuTI88DAzhMYC99I8BWv7zYP4A1puo5HIjEJ5EX48ighy4ZyKMG9EDXxBgW6e++cn7d1xuFghA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
"node_modules/file-uri-to-path": {
"version": "1.0.0",
"license": "MIT"
@@ -37382,6 +37463,13 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/foreach": {
+ "version": "2.0.6",
+ "resolved": "https://registry.npmjs.org/foreach/-/foreach-2.0.6.tgz",
+ "integrity": "sha512-k6GAGDyqLe9JaebCsFCoudPPWfihKu8pylYXRlqP1J7ms39iPoTtk2fviNglIeQEwdh0bQeKJ01ZPyuyQvKzwg==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/foreground-child": {
"version": "3.3.1",
"dev": true,
@@ -37913,6 +38001,16 @@
"unicode-trie": "^2.0.0"
}
},
+ "node_modules/graphlib": {
+ "version": "2.1.8",
+ "resolved": "https://registry.npmjs.org/graphlib/-/graphlib-2.1.8.tgz",
+ "integrity": "sha512-jcLLfkpoVGmH7/InMC/1hIvOPSUh38oJtGhvrOFGzioE1DZ+0YW16RgmOJhHiuWTvGiJQ9Z1Ik43JvkRPRvE+A==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "lodash": "^4.17.15"
+ }
+ },
"node_modules/graphql": {
"version": "16.14.2",
"license": "MIT",
@@ -38307,6 +38405,13 @@
}
}
},
+ "node_modules/http-reasons": {
+ "version": "0.1.0",
+ "resolved": "https://registry.npmjs.org/http-reasons/-/http-reasons-0.1.0.tgz",
+ "integrity": "sha512-P6kYh0lKZ+y29T2Gqz+RlC9WBLhKe8kDmcJ+A+611jFfxdPsbMRQ5aNmFRM3lENqFkK+HTTL+tlQviAiv0AbLQ==",
+ "dev": true,
+ "license": "Apache-2.0"
+ },
"node_modules/http-response-object": {
"version": "3.0.2",
"resolved": "https://registry.npmjs.org/http-response-object/-/http-response-object-3.0.2.tgz",
@@ -38324,6 +38429,13 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/http2-client": {
+ "version": "1.3.5",
+ "resolved": "https://registry.npmjs.org/http2-client/-/http2-client-1.3.5.tgz",
+ "integrity": "sha512-EC2utToWl4RKfs5zd36Mxq7nzHHBuomZboI0yYL6Y0RmBgT7Sgkq4rQ0ezFTYoIsSs7Tm9SJe+o2FcAg6GBhGA==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/https-browserify": {
"version": "1.0.0",
"dev": true,
@@ -41755,10 +41867,45 @@
"version": "2.3.1",
"license": "MIT"
},
+ "node_modules/json-pointer": {
+ "version": "0.6.2",
+ "resolved": "https://registry.npmjs.org/json-pointer/-/json-pointer-0.6.2.tgz",
+ "integrity": "sha512-vLWcKbOaXlO+jvRy4qNd+TI1QUPZzfJj1tpJ3vAXDych5XJf93ftpUKe5pKCrzyIIwgBJcOcCVRUfqQP25afBw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "foreach": "^2.0.4"
+ }
+ },
"node_modules/json-schema": {
"version": "0.4.0",
"license": "(AFL-2.1 OR BSD-3-Clause)"
},
+ "node_modules/json-schema-compare": {
+ "version": "0.2.2",
+ "resolved": "https://registry.npmjs.org/json-schema-compare/-/json-schema-compare-0.2.2.tgz",
+ "integrity": "sha512-c4WYmDKyJXhs7WWvAWm3uIYnfyWFoIp+JEoX34rctVvEkMYCPGhXtvmFFXiffBbxfZsvQ0RNnV5H7GvDF5HCqQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "lodash": "^4.17.4"
+ }
+ },
+ "node_modules/json-schema-merge-allof": {
+ "version": "0.8.1",
+ "resolved": "https://registry.npmjs.org/json-schema-merge-allof/-/json-schema-merge-allof-0.8.1.tgz",
+ "integrity": "sha512-CTUKmIlPJbsWfzRRnOXz+0MjIqvnleIXwFTzz+t9T86HnYX/Rozria6ZVGLktAU9e+NygNljveP+yxqtQp/Q4w==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "compute-lcm": "^1.1.2",
+ "json-schema-compare": "^0.2.2",
+ "lodash": "^4.17.20"
+ },
+ "engines": {
+ "node": ">=12.0.0"
+ }
+ },
"node_modules/json-schema-traverse": {
"version": "1.0.0",
"license": "MIT"
@@ -42688,6 +42835,16 @@
"version": "1.2.4",
"license": "MIT"
},
+ "node_modules/liquid-json": {
+ "version": "0.3.1",
+ "resolved": "https://registry.npmjs.org/liquid-json/-/liquid-json-0.3.1.tgz",
+ "integrity": "sha512-wUayTU8MS827Dam6MxgD72Ui+KOSF+u/eIqpatOtjnvgJ0+mnDq33uC2M7J0tPK+upe/DpUAuK4JUU89iBoNKQ==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "engines": {
+ "node": ">=4"
+ }
+ },
"node_modules/listenercount": {
"version": "1.0.1",
"resolved": "https://registry.npmjs.org/listenercount/-/listenercount-1.0.1.tgz",
@@ -44337,6 +44494,19 @@
"dev": true,
"license": "MIT"
},
+ "node_modules/mime": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/mime/-/mime-3.0.0.tgz",
+ "integrity": "sha512-jSCU7/VB1loIWBZe14aEYHU/+1UMEHoaO7qxCOVJOw9GgH72VAWppxNcjU+x9a2k3GSIBXNKxXQFqRvvZ7vr3A==",
+ "dev": true,
+ "license": "MIT",
+ "bin": {
+ "mime": "cli.js"
+ },
+ "engines": {
+ "node": ">=10.0.0"
+ }
+ },
"node_modules/mime-db": {
"version": "1.52.0",
"license": "MIT",
@@ -44344,6 +44514,16 @@
"node": ">= 0.6"
}
},
+ "node_modules/mime-format": {
+ "version": "2.0.2",
+ "resolved": "https://registry.npmjs.org/mime-format/-/mime-format-2.0.2.tgz",
+ "integrity": "sha512-Y5ERWVcyh3sby9Fx2U5F1yatiTFjNsqF5NltihTWI9QgNtr5o3dbCZdcKa1l2wyfhnwwoP9HGNxga7LqZLA6gw==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "charset": "^1.0.0"
+ }
+ },
"node_modules/mime-types": {
"version": "2.1.35",
"license": "MIT",
@@ -44991,6 +45171,16 @@
"version": "2.6.2",
"license": "MIT"
},
+ "node_modules/neotraverse": {
+ "version": "0.6.15",
+ "resolved": "https://registry.npmjs.org/neotraverse/-/neotraverse-0.6.15.tgz",
+ "integrity": "sha512-HZpdkco+JeXq0G+WWpMJ4NsX3pqb5O7eR9uGz3FfoFt+LYzU8iRWp49nJtud6hsDoywM8tIrDo3gjgmOqJA8LA==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 10"
+ }
+ },
"node_modules/netmask": {
"version": "2.1.1",
"license": "MIT",
@@ -45080,6 +45270,19 @@
}
}
},
+ "node_modules/node-fetch-h2": {
+ "version": "2.3.0",
+ "resolved": "https://registry.npmjs.org/node-fetch-h2/-/node-fetch-h2-2.3.0.tgz",
+ "integrity": "sha512-ofRW94Ab0T4AOh5Fk8t0h8OBWrmjb0SSB20xh1H8YnPV9EJ+f5AMoYSUQ2zgJ4Iq2HAK0I2l5/Nequ8YzFS3Hg==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "http2-client": "^1.2.5"
+ },
+ "engines": {
+ "node": "4.x || >=6.0.0"
+ }
+ },
"node_modules/node-fetch-native": {
"version": "1.6.7",
"resolved": "https://registry.npmjs.org/node-fetch-native/-/node-fetch-native-1.6.7.tgz",
@@ -45175,6 +45378,23 @@
"node": ">=18.0.0"
}
},
+ "node_modules/node-readfiles": {
+ "version": "0.2.0",
+ "resolved": "https://registry.npmjs.org/node-readfiles/-/node-readfiles-0.2.0.tgz",
+ "integrity": "sha512-SU00ZarexNlE4Rjdm83vglt5Y9yiQ+XI1XpflWlb7q7UTN1JUItm69xMeiQCTxtTfnzt+83T8Cx+vI2ED++VDA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "es6-promise": "^3.2.1"
+ }
+ },
+ "node_modules/node-readfiles/node_modules/es6-promise": {
+ "version": "3.3.1",
+ "resolved": "https://registry.npmjs.org/es6-promise/-/es6-promise-3.3.1.tgz",
+ "integrity": "sha512-SOp9Phqvqn7jtEUxPWdWfWoLmyt2VaJ6MpvP9Comy1MceMXqE6bxvaTu4iaxpYYPzhny28Lc+M87/c2cPK6lDg==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/node-releases": {
"version": "2.0.57",
"resolved": "https://registry.npmjs.org/node-releases/-/node-releases-2.0.57.tgz",
@@ -45360,6 +45580,142 @@
"version": "4.11.6",
"license": "MIT"
},
+ "node_modules/oas-kit-common": {
+ "version": "1.0.8",
+ "resolved": "https://registry.npmjs.org/oas-kit-common/-/oas-kit-common-1.0.8.tgz",
+ "integrity": "sha512-pJTS2+T0oGIwgjGpw7sIRU8RQMcUoKCDWFLdBqKB2BNmGpbBMH2sdqAaOXUg8OzonZHU0L7vfJu1mJFEiYDWOQ==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "fast-safe-stringify": "^2.0.7"
+ }
+ },
+ "node_modules/oas-linter": {
+ "version": "3.2.2",
+ "resolved": "https://registry.npmjs.org/oas-linter/-/oas-linter-3.2.2.tgz",
+ "integrity": "sha512-KEGjPDVoU5K6swgo9hJVA/qYGlwfbFx+Kg2QB/kd7rzV5N8N5Mg6PlsoCMohVnQmo+pzJap/F610qTodKzecGQ==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "@exodus/schemasafe": "^1.0.0-rc.2",
+ "should": "^13.2.1",
+ "yaml": "^1.10.0"
+ },
+ "funding": {
+ "url": "https://github.com/Mermade/oas-kit?sponsor=1"
+ }
+ },
+ "node_modules/oas-linter/node_modules/yaml": {
+ "version": "1.10.3",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.3.tgz",
+ "integrity": "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
+ "node_modules/oas-resolver": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/oas-resolver/-/oas-resolver-2.5.6.tgz",
+ "integrity": "sha512-Yx5PWQNZomfEhPPOphFbZKi9W93CocQj18NlD2Pa4GWZzdZpSJvYwoiuurRI7m3SpcChrnO08hkuQDL3FGsVFQ==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "node-fetch-h2": "^2.3.0",
+ "oas-kit-common": "^1.0.8",
+ "reftools": "^1.1.9",
+ "yaml": "^1.10.0",
+ "yargs": "^17.0.1"
+ },
+ "bin": {
+ "resolve": "resolve.js"
+ },
+ "funding": {
+ "url": "https://github.com/Mermade/oas-kit?sponsor=1"
+ }
+ },
+ "node_modules/oas-resolver-browser": {
+ "version": "2.5.6",
+ "resolved": "https://registry.npmjs.org/oas-resolver-browser/-/oas-resolver-browser-2.5.6.tgz",
+ "integrity": "sha512-Jw5elT/kwUJrnGaVuRWe1D7hmnYWB8rfDDjBnpQ+RYY/dzAewGXeTexXzt4fGEo6PUE4eqKqPWF79MZxxvMppA==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "node-fetch-h2": "^2.3.0",
+ "oas-kit-common": "^1.0.8",
+ "path-browserify": "^1.0.1",
+ "reftools": "^1.1.9",
+ "yaml": "^1.10.0",
+ "yargs": "^17.0.1"
+ },
+ "bin": {
+ "resolve": "resolve.js"
+ },
+ "funding": {
+ "url": "https://github.com/Mermade/oas-kit?sponsor=1"
+ }
+ },
+ "node_modules/oas-resolver-browser/node_modules/yaml": {
+ "version": "1.10.3",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.3.tgz",
+ "integrity": "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
+ "node_modules/oas-resolver/node_modules/yaml": {
+ "version": "1.10.3",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.3.tgz",
+ "integrity": "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
+ "node_modules/oas-schema-walker": {
+ "version": "1.1.5",
+ "resolved": "https://registry.npmjs.org/oas-schema-walker/-/oas-schema-walker-1.1.5.tgz",
+ "integrity": "sha512-2yucenq1a9YPmeNExoUa9Qwrt9RFkjqaMAA1X+U7sbb0AqBeTIdMHky9SQQ6iN94bO5NW0W4TRYXerG+BdAvAQ==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "funding": {
+ "url": "https://github.com/Mermade/oas-kit?sponsor=1"
+ }
+ },
+ "node_modules/oas-validator": {
+ "version": "5.0.8",
+ "resolved": "https://registry.npmjs.org/oas-validator/-/oas-validator-5.0.8.tgz",
+ "integrity": "sha512-cu20/HE5N5HKqVygs3dt94eYJfBi0TsZvPVXDhbXQHiEityDN+RROTleefoKRKKJ9dFAF2JBkDHgvWj0sjKGmw==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "call-me-maybe": "^1.0.1",
+ "oas-kit-common": "^1.0.8",
+ "oas-linter": "^3.2.2",
+ "oas-resolver": "^2.5.6",
+ "oas-schema-walker": "^1.1.5",
+ "reftools": "^1.1.9",
+ "should": "^13.2.1",
+ "yaml": "^1.10.0"
+ },
+ "funding": {
+ "url": "https://github.com/Mermade/oas-kit?sponsor=1"
+ }
+ },
+ "node_modules/oas-validator/node_modules/yaml": {
+ "version": "1.10.3",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.3.tgz",
+ "integrity": "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
"node_modules/oauth-sign": {
"version": "0.9.0",
"license": "Apache-2.0",
@@ -45374,6 +45730,16 @@
"node": ">=0.10.0"
}
},
+ "node_modules/object-hash": {
+ "version": "3.0.0",
+ "resolved": "https://registry.npmjs.org/object-hash/-/object-hash-3.0.0.tgz",
+ "integrity": "sha512-RSn9F68PjH9HqtltsSnqYC1XXoWe9Bju5+213R98cNGttag9q9yAOTzdbsqvIa7aNm5WffBZFpWYr2aWrklWAw==",
+ "dev": true,
+ "license": "MIT",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
"node_modules/object-inspect": {
"version": "1.13.4",
"license": "MIT",
@@ -45592,6 +45958,97 @@
"protobufjs": "^7.2.4"
}
},
+ "node_modules/openapi-to-postmanv2": {
+ "version": "6.4.0",
+ "resolved": "https://registry.npmjs.org/openapi-to-postmanv2/-/openapi-to-postmanv2-6.4.0.tgz",
+ "integrity": "sha512-28wYHG6prl0ldDyZcRCkp46w0gUkJH8/06l2lgFy3bdn+b/6NQCZ9supegkUkcYRvu1YWREEt6OLDLPy3DeFZg==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "ajv": "^8.11.0",
+ "ajv-draft-04": "1.0.0",
+ "ajv-formats": "2.1.1",
+ "async": "3.2.6",
+ "commander": "2.20.3",
+ "graphlib": "2.1.8",
+ "js-yaml": "4.3.0",
+ "json-pointer": "0.6.2",
+ "json-schema-merge-allof": "0.8.1",
+ "lodash": "4.18.1",
+ "neotraverse": "0.6.15",
+ "oas-resolver-browser": "2.5.6",
+ "object-hash": "3.0.0",
+ "openapi-types": "^12.1.3",
+ "path-browserify": "1.0.1",
+ "postman-collection": "^5.0.0",
+ "swagger2openapi": "7.0.8",
+ "yaml": "1.10.2"
+ },
+ "bin": {
+ "openapi2postmanv2": "bin/openapi2postmanv2.js"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/openapi-to-postmanv2/node_modules/ajv-formats": {
+ "version": "2.1.1",
+ "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-2.1.1.tgz",
+ "integrity": "sha512-Wx0Kx52hxE7C18hkMEggYlEifqWZtYaRgouJor+WMdPnQyEK13vgEWyVNup7SoeeoLMsr4kf5h6dOW11I15MUA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "ajv": "^8.0.0"
+ },
+ "peerDependencies": {
+ "ajv": "^8.0.0"
+ },
+ "peerDependenciesMeta": {
+ "ajv": {
+ "optional": true
+ }
+ }
+ },
+ "node_modules/openapi-to-postmanv2/node_modules/js-yaml": {
+ "version": "4.3.0",
+ "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz",
+ "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==",
+ "dev": true,
+ "funding": [
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/puzrin"
+ },
+ {
+ "type": "github",
+ "url": "https://github.com/sponsors/nodeca"
+ }
+ ],
+ "license": "MIT",
+ "dependencies": {
+ "argparse": "^2.0.1"
+ },
+ "bin": {
+ "js-yaml": "bin/js-yaml.js"
+ }
+ },
+ "node_modules/openapi-to-postmanv2/node_modules/yaml": {
+ "version": "1.10.2",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.2.tgz",
+ "integrity": "sha512-r3vXyErRCYJ7wg28yvBY5VSoAF8ZvlcW9/BwUzEtUsjvX/DKs24dIkuwjtuprwJJHsbyUbLApepYTR1BN4uHrg==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
+ "node_modules/openapi-types": {
+ "version": "12.1.3",
+ "resolved": "https://registry.npmjs.org/openapi-types/-/openapi-types-12.1.3.tgz",
+ "integrity": "sha512-N4YtSYJqghVu4iek2ZUvcN/0aqH1kRDuNqzcycDxhOUpg7GdvLa2F3DgS6yBNhInhv2r/6I0Flkn7CqL8+nIcw==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/option": {
"version": "0.2.4",
"resolved": "https://registry.npmjs.org/option/-/option-0.2.4.tgz",
@@ -46244,6 +46701,79 @@
"version": "4.2.0",
"license": "MIT"
},
+ "node_modules/postman-collection": {
+ "version": "5.3.1",
+ "resolved": "https://registry.npmjs.org/postman-collection/-/postman-collection-5.3.1.tgz",
+ "integrity": "sha512-+ixY4KEGerw3I5dE6obXgXx31na8URU5ODNIA6Rjkbt3/BUpNRk03pxUAZFHr5dDXwCikJSa7pt5o0x1QXT77w==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "@faker-js/faker": "5.5.3",
+ "file-type": "3.9.0",
+ "http-reasons": "0.1.0",
+ "iconv-lite": "0.6.3",
+ "liquid-json": "0.3.1",
+ "lodash": "4.18.1",
+ "mime": "3.0.0",
+ "mime-format": "2.0.2",
+ "postman-url-encoder": "3.0.8",
+ "semver": "7.7.1",
+ "uuid": "8.3.2"
+ },
+ "engines": {
+ "node": ">=18"
+ }
+ },
+ "node_modules/postman-collection/node_modules/iconv-lite": {
+ "version": "0.6.3",
+ "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
+ "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "safer-buffer": ">= 2.1.2 < 3.0.0"
+ },
+ "engines": {
+ "node": ">=0.10.0"
+ }
+ },
+ "node_modules/postman-collection/node_modules/semver": {
+ "version": "7.7.1",
+ "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.1.tgz",
+ "integrity": "sha512-hlq8tAfn0m/61p4BVRcPzIGr6LKiMwo4VM6dGi6pt4qcRkmNzTcWq6eCEjEh+qXjkMDvPlOFFSGwQjoEa6gyMA==",
+ "dev": true,
+ "license": "ISC",
+ "bin": {
+ "semver": "bin/semver.js"
+ },
+ "engines": {
+ "node": ">=10"
+ }
+ },
+ "node_modules/postman-collection/node_modules/uuid": {
+ "version": "8.3.2",
+ "resolved": "https://registry.npmjs.org/uuid/-/uuid-8.3.2.tgz",
+ "integrity": "sha512-+NYs2QeMWy+GWFOEm9xnn6HCDp0l7QBD7ml8zLUmJ+93Q5NF0NocErnwkTkXVFNiX3/fpC6afS8Dhb/gz7R7eg==",
+ "deprecated": "uuid@10 and below is no longer supported. For ESM codebases, update to uuid@latest. For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).",
+ "dev": true,
+ "license": "MIT",
+ "bin": {
+ "uuid": "dist/bin/uuid"
+ }
+ },
+ "node_modules/postman-url-encoder": {
+ "version": "3.0.8",
+ "resolved": "https://registry.npmjs.org/postman-url-encoder/-/postman-url-encoder-3.0.8.tgz",
+ "integrity": "sha512-EOgUMBazo7JNP4TDrd64TsooCiWzzo4143Ws8E8WYGEpn2PKpq+S4XRTDhuRTYHm3VKOpUZs7ZYZq7zSDuesqA==",
+ "dev": true,
+ "license": "Apache-2.0",
+ "dependencies": {
+ "punycode": "^2.3.1"
+ },
+ "engines": {
+ "node": ">=10"
+ }
+ },
"node_modules/postprocessing": {
"version": "6.39.5",
"resolved": "https://registry.npmjs.org/postprocessing/-/postprocessing-6.39.5.tgz",
@@ -47222,6 +47752,16 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/reftools": {
+ "version": "1.1.9",
+ "resolved": "https://registry.npmjs.org/reftools/-/reftools-1.1.9.tgz",
+ "integrity": "sha512-OVede/NQE13xBQ+ob5CKd5KyeJYU2YInb1bmV4nRoOfquZPkAkxuOXicSe1PvqIuZZ4kD13sPKBbR7UFDmli6w==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "funding": {
+ "url": "https://github.com/Mermade/oas-kit?sponsor=1"
+ }
+ },
"node_modules/regenerate": {
"version": "1.4.2",
"dev": true,
@@ -49069,6 +49609,66 @@
"node": ">=14.17.0"
}
},
+ "node_modules/should": {
+ "version": "13.2.3",
+ "resolved": "https://registry.npmjs.org/should/-/should-13.2.3.tgz",
+ "integrity": "sha512-ggLesLtu2xp+ZxI+ysJTmNjh2U0TsC+rQ/pfED9bUZZ4DKefP27D+7YJVVTvKsmjLpIi9jAa7itwDGkDDmt1GQ==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "should-equal": "^2.0.0",
+ "should-format": "^3.0.3",
+ "should-type": "^1.4.0",
+ "should-type-adaptors": "^1.0.1",
+ "should-util": "^1.0.0"
+ }
+ },
+ "node_modules/should-equal": {
+ "version": "2.0.0",
+ "resolved": "https://registry.npmjs.org/should-equal/-/should-equal-2.0.0.tgz",
+ "integrity": "sha512-ZP36TMrK9euEuWQYBig9W55WPC7uo37qzAEmbjHz4gfyuXrEUgF8cUvQVO+w+d3OMfPvSRQJ22lSm8MQJ43LTA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "should-type": "^1.4.0"
+ }
+ },
+ "node_modules/should-format": {
+ "version": "3.0.3",
+ "resolved": "https://registry.npmjs.org/should-format/-/should-format-3.0.3.tgz",
+ "integrity": "sha512-hZ58adtulAk0gKtua7QxevgUaXTTXxIi8t41L3zo9AHvjXO1/7sdLECuHeIN2SRtYXpNkmhoUP2pdeWgricQ+Q==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "should-type": "^1.3.0",
+ "should-type-adaptors": "^1.0.1"
+ }
+ },
+ "node_modules/should-type": {
+ "version": "1.4.0",
+ "resolved": "https://registry.npmjs.org/should-type/-/should-type-1.4.0.tgz",
+ "integrity": "sha512-MdAsTu3n25yDbIe1NeN69G4n6mUnJGtSJHygX3+oN0ZbO3DTiATnf7XnYJdGT42JCXurTb1JI0qOBR65shvhPQ==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/should-type-adaptors": {
+ "version": "1.1.0",
+ "resolved": "https://registry.npmjs.org/should-type-adaptors/-/should-type-adaptors-1.1.0.tgz",
+ "integrity": "sha512-JA4hdoLnN+kebEp2Vs8eBe9g7uy0zbRo+RMcU0EsNy+R+k049Ki+N5tT5Jagst2g7EAja+euFuoXFCa8vIklfA==",
+ "dev": true,
+ "license": "MIT",
+ "dependencies": {
+ "should-type": "^1.3.0",
+ "should-util": "^1.0.0"
+ }
+ },
+ "node_modules/should-util": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/should-util/-/should-util-1.0.1.tgz",
+ "integrity": "sha512-oXF8tfxx5cDk8r2kYqlkUJzZpDBqVY/II2WhvU0n9Y3XYvAYRmeaf1PvvIvTgPnv4KJ+ES5M0PyDq5Jp+Ygy2g==",
+ "dev": true,
+ "license": "MIT"
+ },
"node_modules/side-channel": {
"version": "1.1.0",
"license": "MIT",
@@ -49973,6 +50573,44 @@
"url": "https://github.com/sponsors/ljharb"
}
},
+ "node_modules/swagger2openapi": {
+ "version": "7.0.8",
+ "resolved": "https://registry.npmjs.org/swagger2openapi/-/swagger2openapi-7.0.8.tgz",
+ "integrity": "sha512-upi/0ZGkYgEcLeGieoz8gT74oWHA0E7JivX7aN9mAf+Tc7BQoRBvnIGHoPDw+f9TXTW4s6kGYCZJtauP6OYp7g==",
+ "dev": true,
+ "license": "BSD-3-Clause",
+ "dependencies": {
+ "call-me-maybe": "^1.0.1",
+ "node-fetch": "^2.6.1",
+ "node-fetch-h2": "^2.3.0",
+ "node-readfiles": "^0.2.0",
+ "oas-kit-common": "^1.0.8",
+ "oas-resolver": "^2.5.6",
+ "oas-schema-walker": "^1.1.5",
+ "oas-validator": "^5.0.8",
+ "reftools": "^1.1.9",
+ "yaml": "^1.10.0",
+ "yargs": "^17.0.1"
+ },
+ "bin": {
+ "boast": "boast.js",
+ "oas-validate": "oas-validate.js",
+ "swagger2openapi": "swagger2openapi.js"
+ },
+ "funding": {
+ "url": "https://github.com/Mermade/oas-kit?sponsor=1"
+ }
+ },
+ "node_modules/swagger2openapi/node_modules/yaml": {
+ "version": "1.10.3",
+ "resolved": "https://registry.npmjs.org/yaml/-/yaml-1.10.3.tgz",
+ "integrity": "sha512-vIYeF1u3CjlhAFekPPAk2h/Kv4T3mAkMox5OymRiJQB0spDP10LHvt+K7G9Ny6NuuMAb25/6n1qyUjAcGNf/AA==",
+ "dev": true,
+ "license": "ISC",
+ "engines": {
+ "node": ">= 6"
+ }
+ },
"node_modules/symbol-observable": {
"version": "2.0.3",
"license": "MIT",
@@ -52027,6 +52665,44 @@
"node": ">=10.12.0"
}
},
+ "node_modules/validate.io-array": {
+ "version": "1.0.6",
+ "resolved": "https://registry.npmjs.org/validate.io-array/-/validate.io-array-1.0.6.tgz",
+ "integrity": "sha512-DeOy7CnPEziggrOO5CZhVKJw6S3Yi7e9e65R1Nl/RTN1vTQKnzjfvks0/8kQ40FP/dsjRAOd4hxmJ7uLa6vxkg==",
+ "dev": true,
+ "license": "MIT"
+ },
+ "node_modules/validate.io-function": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/validate.io-function/-/validate.io-function-1.0.2.tgz",
+ "integrity": "sha512-LlFybRJEriSuBnUhQyG5bwglhh50EpTL2ul23MPIuR1odjO7XaMLFV8vHGwp7AZciFxtYOeiSCT5st+XSPONiQ==",
+ "dev": true
+ },
+ "node_modules/validate.io-integer": {
+ "version": "1.0.5",
+ "resolved": "https://registry.npmjs.org/validate.io-integer/-/validate.io-integer-1.0.5.tgz",
+ "integrity": "sha512-22izsYSLojN/P6bppBqhgUDjCkr5RY2jd+N2a3DCAUey8ydvrZ/OkGvFPR7qfOpwR2LC5p4Ngzxz36g5Vgr/hQ==",
+ "dev": true,
+ "dependencies": {
+ "validate.io-number": "^1.0.3"
+ }
+ },
+ "node_modules/validate.io-integer-array": {
+ "version": "1.0.0",
+ "resolved": "https://registry.npmjs.org/validate.io-integer-array/-/validate.io-integer-array-1.0.0.tgz",
+ "integrity": "sha512-mTrMk/1ytQHtCY0oNO3dztafHYyGU88KL+jRxWuzfOmQb+4qqnWmI+gykvGp8usKZOM0H7keJHEbRaFiYA0VrA==",
+ "dev": true,
+ "dependencies": {
+ "validate.io-array": "^1.0.3",
+ "validate.io-integer": "^1.0.4"
+ }
+ },
+ "node_modules/validate.io-number": {
+ "version": "1.0.3",
+ "resolved": "https://registry.npmjs.org/validate.io-number/-/validate.io-number-1.0.3.tgz",
+ "integrity": "sha512-kRAyotcbNaSYoDnXvb4MHg/0a1egJdLwS6oJ38TJY7aw9n93Fl/3blIXdyYvPOp55CNxywooG/3BcrwNrBpcSg==",
+ "dev": true
+ },
"node_modules/valtio": {
"version": "2.1.7",
"resolved": "https://registry.npmjs.org/valtio/-/valtio-2.1.7.tgz",
diff --git a/package.json b/package.json
index 78a86e198..45fc8d376 100644
--- a/package.json
+++ b/package.json
@@ -259,7 +259,7 @@
"audit:route-shadowing": "node scripts/audit-route-shadowing.mjs",
"audit:handlers": "node scripts/audit-empty-handlers.mjs",
"audit:x402-catalog": "node scripts/audit-x402-catalog.mjs",
- "gate": "npm run check:conflicts && npm run check:claude && npm run check:cli-scripts && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run check:mcp-counts && npm run test:mcp-surface && npm run check:mcp-catalog && npm run audit:mcp-listing && npm run audit:mcp-surfaces && npm run check:pay-skills && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run check:prompt-library && npm run audit:docs && npm run check:docs-freshness && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:ios-app && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run check:skills-pack && npm run check:skill-repos && npm run check:well-known-skills && npm run check:openai-fields && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
+ "gate": "npm run check:conflicts && npm run check:claude && npm run check:cli-scripts && npm run check:vendored && npm run check:model-viewer && npm run check:gcloudignore && npm run check:fetch-timeouts && npm run check:tdz-bootstrap && npm run check:event && npm run check:cron-syntax && npm run check:home-matrix && npm run check:studio-openapi && npm run test:gate && npm run test:gate-3d && npm run audit:mcp && npm run audit:mcp-golden && npm run audit:mcp-safety && npm run audit:mcp-catalog && npm run check:mcp-counts && npm run test:mcp-surface && npm run check:mcp-catalog && npm run audit:mcp-listing && npm run audit:mcp-surfaces && npm run check:pay-skills && npm run audit:routes && npm run audit:handlers && npm run audit:pages && npm run audit:links && npm run check:awesome && npm run check:prompt-library && npm run audit:docs && npm run check:docs-freshness && npm run audit:upstreams && npm run check:tutorials && npm run audit:hidden-guard && npm run audit:inline-handlers && npm run audit:x402-catalog && npm run audit:tokens && npm run audit:states && npm run audit:motion-tokens && npm run audit:guards && npm run audit:tour-atlas && npm run check:ios-icons && npm run check:macos-icon && npm run check:apple-widget && npm run check:ios-app && npm run check:windows-widget && npm run check:announce && npm run i18n:home && npm run check:skills-seed && npm run check:openai-skills && npm run check:skills-pack && npm run check:skill-repos && npm run check:well-known-skills && npm run check:postman-collection && npm run check:openai-fields && npm run audit:motion && npm run audit:tour-global && npm run check:doc-media && npm run check:images && npm run audit:route-shadowing",
"test:stake-program": "node scripts/test-event-markets-stake.mjs",
"test:gate-3d": "vitest run tests/glb-canonicalize.test.js tests/animation-retarget.test.js tests/animation-retarget-rest-pollution.test.js tests/viewer-framing.test.js",
"audit:mcp-golden": "node scripts/audit-mcp-golden.mjs",
@@ -506,6 +506,8 @@
"check:skill-repos": "node scripts/build-standalone-skill-repos.mjs --check",
"build:well-known-skills": "node scripts/build-well-known-skills-index.mjs",
"check:well-known-skills": "node scripts/build-well-known-skills-index.mjs --check",
+ "build:postman-collection": "node scripts/build-postman-collection.mjs",
+ "check:postman-collection": "node scripts/build-postman-collection.mjs --check",
"build:openai-fields": "node scripts/build-openai-portal-fields.mjs",
"check:openai-fields": "node scripts/build-openai-portal-fields.mjs --check",
"build:skills-seed": "node scripts/build-skills-seed.mjs",
@@ -753,6 +755,7 @@
"i18n-iso-countries": "^7.14.0",
"jsdom": "30.0.1",
"json5": "^2.2.3",
+ "openapi-to-postmanv2": "^6.4.0",
"playwright": "^1.63.0",
"prettier": "^3.9.8",
"puppeteer": "^25.10.0",
diff --git a/public/.well-known/openapi.yaml b/public/.well-known/openapi.yaml
index 0cf7dd8ea..44289a1ef 100644
--- a/public/.well-known/openapi.yaml
+++ b/public/.well-known/openapi.yaml
@@ -893,7 +893,7 @@ paths:
$ref: '#/components/schemas/Cursor'
- name: totals
in: query
- description: When `1`, include `total` and `total_views` in the response. Adds a second SQL roundtrip — request only on the first page.
+ description: When `1`, include `total` and `total_views` in the response. Adds a second SQL roundtrip, so request it only on the first page.
schema:
type: string
enum: ['1']
@@ -1142,7 +1142,7 @@ paths:
summary: Create a new API key
description: >
The `secret` field in the response is the only time the plaintext key
- is returned — store it immediately.
+ is returned: store it immediately.
security:
- cookieAuth: []
requestBody:
@@ -1343,7 +1343,7 @@ paths:
get:
operationId: oauthAuthorize
tags: [OAuth]
- summary: Authorization endpoint — show consent screen
+ summary: Authorization endpoint (show consent screen)
description: >
If the user is not authenticated they are redirected to the login page.
On success, displays an HTML consent form. Requires PKCE with
@@ -1470,7 +1470,7 @@ paths:
post:
operationId: oauthToken
tags: [OAuth]
- summary: Token endpoint — exchange code or refresh token
+ summary: Token endpoint (exchange code or refresh token)
description: >
Supports `authorization_code` and `refresh_token` grant types.
Confidential clients authenticate via HTTP Basic (preferred) or
@@ -1695,7 +1695,7 @@ paths:
id: 2
method: tools/list
toolCall:
- summary: tools/call — render_avatar
+ summary: tools/call (render_avatar)
value:
jsonrpc: '2.0'
id: 3
@@ -1723,7 +1723,7 @@ paths:
get:
operationId: mcpSseStream
tags: [MCP]
- summary: MCP SSE stream (reserved — not yet implemented)
+ summary: MCP SSE stream (reserved, not yet implemented)
security:
- bearerAuth: []
responses:
@@ -1737,7 +1737,7 @@ paths:
delete:
operationId: mcpTerminateSession
tags: [MCP]
- summary: Terminate MCP session (no-op — server is stateless)
+ summary: Terminate MCP session (no-op, server is stateless)
security:
- bearerAuth: []
responses:
@@ -1772,7 +1772,7 @@ paths:
$ref: '#/components/responses/Unauthorized'
# --------------------------------------------------------------------------
- # Discovery — well-known endpoints
+ # Discovery: well-known endpoints
# --------------------------------------------------------------------------
/.well-known/oauth-authorization-server:
get:
@@ -1882,7 +1882,7 @@ paths:
get:
operationId: getAgentCard
tags: [Discovery]
- summary: Agent Card — A2A protocol agent description
+ summary: Agent Card (A2A protocol agent description)
responses:
'200':
description: Agent card JSON
diff --git a/public/.well-known/postman-collection.json b/public/.well-known/postman-collection.json
new file mode 100644
index 000000000..e9df39c92
--- /dev/null
+++ b/public/.well-known/postman-collection.json
@@ -0,0 +1,1799 @@
+{
+ "item": [
+ {
+ "name": "Load the 3D model viewer interface",
+ "request": {
+ "name": "Load the 3D model viewer interface",
+ "description": {
+ "content": "Returns the main viewer page where users can drag-and-drop glTF/GLB 3D models for instant preview.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ ""
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "api",
+ "item": [
+ {
+ "name": "solana/atomic",
+ "item": [
+ {
+ "name": "Read Transaction V1 status or inspect a confirmed transaction",
+ "request": {
+ "name": "Read Transaction V1 status or inspect a confirmed transaction",
+ "description": {
+ "content": "With no query parameter, returns Solana mainnet Transaction V1 activation status. With `signature`, fetches a confirmed transaction using `maxSupportedTransactionVersion: 1` and returns its exact wire footprint, normalized resource limits, confirmation metadata, and sponsor-safety assessment. This endpoint never signs, simulates, or broadcasts.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "solana",
+ "atomic"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [
+ {
+ "disabled": false,
+ "key": "signature",
+ "value": "<string>",
+ "description": "Base58 Solana transaction signature. Omit for live V1 status."
+ }
+ ],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Inspect signed Solana wire bytes without broadcasting",
+ "request": {
+ "name": "Inspect signed Solana wire bytes without broadcasting",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "solana",
+ "atomic"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": null,
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"transaction\": \"<byte>\"\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ },
+ {
+ "name": "auth",
+ "item": [
+ {
+ "name": "Register a new user account",
+ "request": {
+ "name": "Register a new user account",
+ "description": {
+ "content": "Creates a user account, hashes the password, opens a session, and sets the `sid` cookie. Rate-limited to **5 requests per IP per hour**.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "auth",
+ "register"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": null,
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"email\": \"<email>\",\n \"password\": \"<string>\",\n \"display_name\": \"<string>\"\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Log in with email and password",
+ "request": {
+ "name": "Log in with email and password",
+ "description": {
+ "content": "Verifies credentials, creates a session, and sets the `sid` cookie. Rate-limited to **30 requests per IP per 10 minutes**.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "auth",
+ "login"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": null,
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"email\": \"<email>\",\n \"password\": \"<string>\"\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Get the currently authenticated user",
+ "request": {
+ "name": "Get the currently authenticated user",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "auth",
+ "me"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Invalidate the current session",
+ "request": {
+ "name": "Invalidate the current session",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "auth",
+ "logout"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ },
+ {
+ "name": "avatars",
+ "item": [
+ {
+ "name": "List avatars owned by the authenticated user",
+ "request": {
+ "name": "List avatars owned by the authenticated user",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "avatars"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [
+ {
+ "disabled": false,
+ "key": "limit",
+ "value": "50"
+ },
+ {
+ "disabled": false,
+ "key": "cursor",
+ "value": "<dateTime>",
+ "description": "Pagination cursor (ISO-8601 timestamp from previous `next_cursor`)"
+ },
+ {
+ "disabled": false,
+ "key": "visibility",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "include_public",
+ "value": "<string>",
+ "description": "When `true`, also returns all public avatars"
+ }
+ ],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Create an avatar record after uploading the file to R2",
+ "request": {
+ "name": "Create an avatar record after uploading the file to R2",
+ "description": {
+ "content": "Call `POST /api/avatars/presign` first to get a presigned upload URL, upload the GLB file directly to R2, then call this endpoint to register the avatar.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "avatars"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ },
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"name\": \"<string>\",\n \"storage_key\": \"<string>\",\n \"size_bytes\": \"<integer>\",\n \"slug\": \"<string>\",\n \"description\": \"<string>\",\n \"visibility\": \"private\",\n \"tags\": [\n \"<string>\",\n \"<string>\"\n ],\n \"source\": \"upload\",\n \"source_meta\": {\n \"additionalProperty\": \"<any>\"\n },\n \"content_type\": \"model/gltf-binary\",\n \"checksum_sha256\": \"<string>\"\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Search public avatars (no authentication required)",
+ "request": {
+ "name": "Search public avatars (no authentication required)",
+ "description": {
+ "content": "Full-text search over public avatars. Results are cached for 60 seconds.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "avatars",
+ "public"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [
+ {
+ "disabled": false,
+ "key": "q",
+ "value": "<string>",
+ "description": "Free-text search query"
+ },
+ {
+ "disabled": false,
+ "key": "tag",
+ "value": "<string>",
+ "description": "Filter by a single tag"
+ },
+ {
+ "disabled": false,
+ "key": "limit",
+ "value": "24"
+ },
+ {
+ "disabled": false,
+ "key": "cursor",
+ "value": "<dateTime>",
+ "description": "Pagination cursor (ISO-8601 timestamp from previous `next_cursor`)"
+ },
+ {
+ "disabled": false,
+ "key": "totals",
+ "value": "<string>",
+ "description": "When `1`, include `total` and `total_views` in the response. Adds a second SQL roundtrip, so request it only on the first page."
+ }
+ ],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Get a presigned URL for uploading a GLB file directly to R2",
+ "request": {
+ "name": "Get a presigned URL for uploading a GLB file directly to R2",
+ "description": {
+ "content": "Rate-limited to **60 requests per user per hour**. Use the returned `upload_url` with an HTTP PUT request (include the `content-type` header). After the upload succeeds, call `POST /api/avatars` with the returned `storage_key`.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "avatars",
+ "presign"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ },
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"size_bytes\": \"<integer>\",\n \"content_type\": \"model/gltf-binary\",\n \"checksum_sha256\": \"<string>\",\n \"slug\": \"<string>\"\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "{id}",
+ "item": [
+ {
+ "name": "Get a single avatar by ID",
+ "request": {
+ "name": "Get a single avatar by ID",
+ "description": {
+ "content": "Returns metadata plus a time-limited (or permanent CDN) URL for the GLB file. Private avatars are only accessible to their owner. Records a `avatar_fetch` usage event.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "avatars",
+ ":id"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": [
+ {
+ "disabled": false,
+ "type": "any",
+ "value": "<uuid>",
+ "key": "id",
+ "description": "(Required) "
+ }
+ ]
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": {
+ "type": "noauth"
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Update avatar metadata (partial update)",
+ "request": {
+ "name": "Update avatar metadata (partial update)",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "avatars",
+ ":id"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": [
+ {
+ "disabled": false,
+ "type": "any",
+ "value": "<uuid>",
+ "key": "id",
+ "description": "(Required) "
+ }
+ ]
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "PATCH",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ },
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"name\": \"<string>\",\n \"description\": \"<string>\",\n \"visibility\": \"<string>\",\n \"tags\": [\n \"<string>\",\n \"<string>\"\n ]\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Delete an avatar (soft delete + queued R2 removal)",
+ "request": {
+ "name": "Delete an avatar (soft delete + queued R2 removal)",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "avatars",
+ ":id"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": [
+ {
+ "disabled": false,
+ "type": "any",
+ "value": "<uuid>",
+ "key": "id",
+ "description": "(Required) "
+ }
+ ]
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "DELETE",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ }
+ ],
+ "event": []
+ },
+ {
+ "name": "keys",
+ "item": [
+ {
+ "name": "List API keys for the authenticated user",
+ "request": {
+ "name": "List API keys for the authenticated user",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "keys"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Create a new API key",
+ "request": {
+ "name": "Create a new API key",
+ "description": {
+ "content": "The `secret` field in the response is the only time the plaintext key is returned: store it immediately.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "keys"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ },
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"name\": \"<string>\",\n \"scope\": \"avatars:read avatars:write\",\n \"expires_in_days\": \"<integer>\",\n \"environment\": \"live\"\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Revoke an API key by ID",
+ "request": {
+ "name": "Revoke an API key by ID",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "keys",
+ ":id"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": [
+ {
+ "disabled": false,
+ "type": "any",
+ "value": "<uuid>",
+ "key": "id",
+ "description": "(Required) "
+ }
+ ]
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "DELETE",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ },
+ {
+ "name": "oauth",
+ "item": [
+ {
+ "name": "Dynamic client registration (RFC 7591)",
+ "request": {
+ "name": "Dynamic client registration (RFC 7591)",
+ "description": {
+ "content": "Registers a new OAuth client. Clients with `redirect_uris` pointing to `localhost` or with `token_endpoint_auth_method: none` are treated as **public** clients; all others are **confidential** and receive a `client_secret`.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "oauth",
+ "register"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": null,
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"redirect_uris\": [\n \"<uri>\"\n ],\n \"client_name\": \"<string>\",\n \"client_uri\": \"<uri>\",\n \"logo_uri\": \"<uri>\",\n \"scope\": \"<string>\",\n \"grant_types\": [\n \"<string>\",\n \"<string>\"\n ],\n \"response_types\": [\n \"<string>\",\n \"<string>\"\n ],\n \"token_endpoint_auth_method\": \"<string>\",\n \"software_id\": \"<string>\",\n \"software_version\": \"<string>\"\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "authorize",
+ "item": [
+ {
+ "name": "Authorization endpoint (show consent screen)",
+ "request": {
+ "name": "Authorization endpoint (show consent screen)",
+ "description": {
+ "content": "If the user is not authenticated they are redirected to the login page. On success, displays an HTML consent form. Requires PKCE with `code_challenge_method=S256`.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "oauth",
+ "authorize"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [
+ {
+ "disabled": false,
+ "key": "response_type",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "client_id",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "redirect_uri",
+ "value": "<uri>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "scope",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "state",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "code_challenge",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "code_challenge_method",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "resource",
+ "value": "<uri>"
+ }
+ ],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "text/html"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Submit consent form decision (allow or deny)",
+ "request": {
+ "name": "Submit consent form decision (allow or deny)",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "oauth",
+ "authorize"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/x-www-form-urlencoded"
+ }
+ ],
+ "method": "POST",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ },
+ "body": {
+ "mode": "urlencoded",
+ "urlencoded": [
+ {
+ "disabled": false,
+ "key": "decision",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "client_id",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "redirect_uri",
+ "value": "<uri>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "code_challenge",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "code_challenge_method",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "response_type",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "scope",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "state",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "resource",
+ "value": "<string>"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ },
+ {
+ "name": "Token endpoint (exchange code or refresh token)",
+ "request": {
+ "name": "Token endpoint (exchange code or refresh token)",
+ "description": {
+ "content": "Supports `authorization_code` and `refresh_token` grant types. Confidential clients authenticate via HTTP Basic (preferred) or `client_id` + `client_secret` form fields. Rate-limited to **120 requests per client per minute**.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "oauth",
+ "token"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/x-www-form-urlencoded"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": null,
+ "body": {
+ "mode": "urlencoded",
+ "urlencoded": [
+ {
+ "disabled": false,
+ "key": "grant_type",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "code",
+ "value": "<string>",
+ "description": "Required for authorization_code grant"
+ },
+ {
+ "disabled": false,
+ "key": "redirect_uri",
+ "value": "<uri>",
+ "description": "Required for authorization_code grant; must match the authorization request"
+ },
+ {
+ "disabled": false,
+ "key": "code_verifier",
+ "value": "<string>",
+ "description": "PKCE verifier; required for authorization_code grant"
+ },
+ {
+ "disabled": false,
+ "key": "refresh_token",
+ "value": "<string>",
+ "description": "Required for refresh_token grant"
+ },
+ {
+ "disabled": false,
+ "key": "scope",
+ "value": "<string>",
+ "description": "Optional subset scope for refresh_token grant"
+ },
+ {
+ "disabled": false,
+ "key": "client_id",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "client_secret",
+ "value": "<string>",
+ "description": "Required for confidential clients not using HTTP Basic"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Token revocation endpoint (RFC 7009)",
+ "request": {
+ "name": "Token revocation endpoint (RFC 7009)",
+ "description": {
+ "content": "Revokes an access token or refresh token. Always returns 200 per the RFC, even if the token is unknown or already revoked.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "oauth",
+ "revoke"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/x-www-form-urlencoded"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": null,
+ "body": {
+ "mode": "urlencoded",
+ "urlencoded": [
+ {
+ "disabled": false,
+ "key": "token",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "token_type_hint",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "client_id",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "client_secret",
+ "value": "<string>"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Token introspection endpoint (RFC 7662)",
+ "request": {
+ "name": "Token introspection endpoint (RFC 7662)",
+ "description": {
+ "content": "Returns metadata about a token. Confidential clients authenticate via HTTP Basic or `client_id`/`client_secret` form fields.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "oauth",
+ "introspect"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/x-www-form-urlencoded"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": null,
+ "body": {
+ "mode": "urlencoded",
+ "urlencoded": [
+ {
+ "disabled": false,
+ "key": "token",
+ "value": "<string>",
+ "description": "(Required) "
+ },
+ {
+ "disabled": false,
+ "key": "client_id",
+ "value": "<string>"
+ },
+ {
+ "disabled": false,
+ "key": "client_secret",
+ "value": "<string>"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ },
+ {
+ "name": "mcp",
+ "item": [
+ {
+ "name": "MCP JSON-RPC 2.0 endpoint",
+ "request": {
+ "name": "MCP JSON-RPC 2.0 endpoint",
+ "description": {
+ "content": "Stateless JSON-RPC 2.0 endpoint implementing the [Model Context Protocol](https://modelcontextprotocol.io). Accepts single or batched requests. Authenticated with an OAuth 2.1 access token **or** an API key in the `Authorization: Bearer …` header.\n\n**Supported methods:** `initialize`, `tools/list`, `tools/call`, `ping`, `notifications/initialized`, `resources/list`, `resources/templates/list`, `prompts/list`, `logging/setLevel`.\n\n**Built-in tools** (via `tools/call`): `list_my_avatars`, `get_avatar`, `search_public_avatars`, `render_avatar`, `delete_avatar`.\n\nRate limits: **600 req/min per IP**, **1 200 req/min per user**.\n",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ "api",
+ "mcp"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Content-Type",
+ "value": "application/json"
+ },
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "POST",
+ "auth": {
+ "type": "bearer",
+ "bearer": [
+ {
+ "key": "token",
+ "value": "{{bearerToken}}"
+ }
+ ]
+ },
+ "body": {
+ "mode": "raw",
+ "raw": "{\n \"jsonrpc\": \"<string>\",\n \"method\": \"<string>\",\n \"id\": \"<string>\",\n \"params\": {\n \"additionalProperty\": \"<any>\"\n }\n}",
+ "options": {
+ "raw": {
+ "language": "json"
+ }
+ }
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "MCP SSE stream (reserved, not yet implemented)",
+ "request": {
+ "name": "MCP SSE stream (reserved, not yet implemented)",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "mcp"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": {
+ "type": "bearer",
+ "bearer": [
+ {
+ "key": "token",
+ "value": "{{bearerToken}}"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Terminate MCP session (no-op, server is stateless)",
+ "request": {
+ "name": "Terminate MCP session (no-op, server is stateless)",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "mcp"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "method": "DELETE",
+ "auth": {
+ "type": "bearer",
+ "bearer": [
+ {
+ "key": "token",
+ "value": "{{bearerToken}}"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ },
+ {
+ "name": "Get usage statistics and quota limits for the current account",
+ "request": {
+ "name": "Get usage statistics and quota limits for the current account",
+ "description": {},
+ "url": {
+ "path": [
+ "api",
+ "usage",
+ "summary"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": {
+ "type": "apikey",
+ "apikey": [
+ {
+ "key": "key",
+ "value": "sid"
+ },
+ {
+ "key": "value",
+ "value": "{{apiKey}}"
+ },
+ {
+ "key": "in",
+ "value": "header"
+ }
+ ]
+ }
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ },
+ {
+ "name": ".well-known",
+ "item": [
+ {
+ "name": "OAuth 2.0 Authorization Server Metadata (RFC 8414)",
+ "request": {
+ "name": "OAuth 2.0 Authorization Server Metadata (RFC 8414)",
+ "description": {
+ "content": "Cached for 300 seconds.",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ ".well-known",
+ "oauth-authorization-server"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "OAuth 2.0 Protected Resource Metadata (RFC 9728)",
+ "request": {
+ "name": "OAuth 2.0 Protected Resource Metadata (RFC 9728)",
+ "description": {
+ "content": "Cached for 300 seconds.",
+ "type": "text/plain"
+ },
+ "url": {
+ "path": [
+ ".well-known",
+ "oauth-protected-resource"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Agent Card (A2A protocol agent description)",
+ "request": {
+ "name": "Agent Card (A2A protocol agent description)",
+ "description": {},
+ "url": {
+ "path": [
+ ".well-known",
+ "agent-card.json"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "Agent registration manifest",
+ "request": {
+ "name": "Agent registration manifest",
+ "description": {},
+ "url": {
+ "path": [
+ ".well-known",
+ "agent-registration.json"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "AI plugin manifest (ChatGPT / OpenAI plugin format)",
+ "request": {
+ "name": "AI plugin manifest (ChatGPT / OpenAI plugin format)",
+ "description": {},
+ "url": {
+ "path": [
+ ".well-known",
+ "ai-plugin.json"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/json"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ },
+ {
+ "name": "This OpenAPI specification",
+ "request": {
+ "name": "This OpenAPI specification",
+ "description": {},
+ "url": {
+ "path": [
+ ".well-known",
+ "openapi.yaml"
+ ],
+ "host": [
+ "{{baseUrl}}"
+ ],
+ "query": [],
+ "variable": []
+ },
+ "header": [
+ {
+ "key": "Accept",
+ "value": "application/yaml"
+ }
+ ],
+ "method": "GET",
+ "auth": null
+ },
+ "response": [],
+ "event": [],
+ "protocolProfileBehavior": {
+ "disableBodyPruning": true
+ }
+ }
+ ],
+ "event": []
+ }
+ ],
+ "event": [],
+ "variable": [
+ {
+ "type": "string",
+ "value": "https://three.ws",
+ "key": "baseUrl"
+ }
+ ],
+ "info": {
+ "name": "three.ws API",
+ "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
+ "description": {
+ "content": "AI-powered 3D avatar management platform. Supports OAuth 2.1 (with PKCE), session cookies, and API keys for authentication. Avatars are stored as glTF/GLB files on Cloudflare R2 and exposed via a Model Context Protocol (MCP) JSON-RPC server for AI tool integrations.\n\n\nContact Support:\n Email: [email protected]",
+ "type": "text/plain"
+ }
+ }
+}
diff --git a/scripts/build-postman-collection.mjs b/scripts/build-postman-collection.mjs
new file mode 100644
index 000000000..e4e7add49
--- /dev/null
+++ b/scripts/build-postman-collection.mjs
@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// Generates the public Postman collection from public/.well-known/openapi.yaml,
+// the same spec the openapi-to-postmanv2 converter also powers for third-party
+// tooling. Keeps the checked-in collection in sync with the spec: run this
+// after editing the OpenAPI file, or check it stays in sync in CI.
+//
+// openapi-to-postmanv2 fakes two things on every run that have nothing to do
+// with the spec: a random `_postman_id`/item `id` on every node, and a random
+// example value for any schema with no fixed shape (free-form objects, and a
+// few numeric/string fields the library fakes even with schemaFaker off). This
+// script strips the ids (Postman assigns its own on import; the schema does
+// not require them) and canonicalizes free-form example bodies to a fixed
+// placeholder, and drops the auto-generated example responses entirely: they
+// are fabricated data, not real API output, and shipping them as if real
+// would violate this repo's no-fake-data rule. What is left (method, URL,
+// path/query parameters, headers, auth, and real request body shapes from the
+// spec) is byte-identical across runs for the same spec.
+//
+// Usage: node scripts/build-postman-collection.mjs [--check]
+// --check exit 1 if the generated output differs from what is on disk
+
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+import { convert } from 'openapi-to-postmanv2';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SPEC_PATH = path.join(ROOT, 'public', '.well-known', 'openapi.yaml');
+const OUT_PATH = path.join(ROOT, 'public', '.well-known', 'postman-collection.json');
+
+function writeAtomic(filePath, contents) {
+ const tmp = `${filePath}.tmp-${process.pid}`;
+ fs.writeFileSync(tmp, contents);
+ fs.renameSync(tmp, filePath);
+}
+
+// Free-form (additionalProperties, no fixed shape) schemas fake a random
+// number of randomly-named keys. Collapse any object whose every key matches
+// that generated shape (key_0, key_1, ...) to one fixed placeholder.
+function canonicalizeFreeform(value) {
+ if (Array.isArray(value)) return value.map(canonicalizeFreeform);
+ if (value && typeof value === 'object') {
+ const keys = Object.keys(value);
+ if (keys.length && keys.every((k) => /^key_\d+$/.test(k))) {
+ return { additionalProperty: '<any>' };
+ }
+ const out = {};
+ for (const k of keys) out[k] = canonicalizeFreeform(value[k]);
+ return out;
+ }
+ return value;
+}
+
+function clean(node) {
+ if (Array.isArray(node)) {
+ node.forEach(clean);
+ return;
+ }
+ if (node && typeof node === 'object') {
+ delete node.id;
+ delete node._postman_id;
+ if (Array.isArray(node.response)) node.response = [];
+ if (node.body && typeof node.body.raw === 'string') {
+ try {
+ const parsed = JSON.parse(node.body.raw);
+ node.body.raw = JSON.stringify(canonicalizeFreeform(parsed), null, 2);
+ } catch {
+ // not JSON (form data, plain text): leave as-is
+ }
+ }
+ for (const key of Object.keys(node)) clean(node[key]);
+ }
+}
+
+function buildCollection() {
+ const spec = fs.readFileSync(SPEC_PATH, 'utf8');
+ return new Promise((resolve, reject) => {
+ convert({ type: 'string', data: spec }, { schemaFaker: false, parametersResolution: 'Example' }, (err, result) => {
+ if (err) return reject(err);
+ if (!result.result) return reject(new Error(result.reason || 'conversion failed'));
+ const collection = result.output[0].data;
+ clean(collection);
+ resolve(collection);
+ });
+ });
+}
+
+const collection = await buildCollection();
+const output = `${JSON.stringify(collection, null, '\t')}\n`;
+
+if (process.argv.includes('--check')) {
+ const onDisk = fs.existsSync(OUT_PATH) ? fs.readFileSync(OUT_PATH, 'utf8') : null;
+ if (onDisk !== output) {
+ console.error(`[build-postman-collection] ${path.relative(ROOT, OUT_PATH)} is out of date with ${path.relative(ROOT, SPEC_PATH)}; run: node scripts/build-postman-collection.mjs`);
+ process.exit(1);
+ }
+ console.log('[build-postman-collection] up to date');
+} else {
+ writeAtomic(OUT_PATH, output);
+ console.log(`[build-postman-collection] wrote ${collection.item.length} top-level item(s) to ${path.relative(ROOT, OUT_PATH)}`);
+}