1stBuddha developer portal

Use 1stBuddha to discover antique Buddha statues and Asian art, inspect current product information, and find documented research. Public catalog reads are free and need no API key, account, trial or sales approval.

Quickstart: public read-only API

Read a current product by the handle from its storefront URL:

curl -H 'Accept: application/json' https://1stbuddha.com/api/v1/products/antique-ayutthaya-buddha-statue-17th-century-museum-piece

The response is current Shopify product JSON: id, title, handle, description, price, available, images and variants. Prices are currency subunits in the storefront market context. Use Shopify UCP for a buyer's cart, shipping, final currency and checkout totals. Recheck price and availability before purchase.

This public API supports GET and HEAD. It has no account access or write operations. Use the same read-only examples as a safe integration test; no test orders or payments are needed.

Authentication and least privilege

Public product reads need no API key. Customer account queries require a registered Shopify client, an authenticated customer's consent, and OAuth authorization code with PKCE S256. Obtain client registration through Shopify; this site does not mint credentials or grant additional access.

The existing authorization server publishes openid, email, customer-account-api:full, customer-account-mcp-api:full, dev.ucp.shopping.checkout:manage, and dev.ucp.shopping.catalog.search:read. Request only the scopes needed for the task. Shopify bundles account access in a full account scope; use unauthenticated public reads for catalog research. Payment always requires the buyer's approval.

Structured errors

The versioned public API returns RFC 9457 application/problem+json errors containing type, title, status, detail, instance, a stable code, and a resolution hint. Unknown /api/ routes use the same recovery format when Shopify returns 404. Existing UCP routes retain their own protocol.

400 invalid_handle: use a handle from a public product URL. 404 product_not_found or api_route_not_found: consult the sitemap or OpenAPI file. 405 method_not_allowed: use GET or HEAD. 429 origin_rate_limited: honor Retry-After. 502 origin_unavailable: retry later. Do not retry a purchase or payment automatically.

Official CLI

The 1stBuddha CLI is distributed directly by 1stBuddha. Download 1stbuddha.mjs, inspect it, and run it with Node.js 20 or later. It uses only public GET requests and requires no dependencies or credentials.

node 1stbuddha.mjs discover
node 1stbuddha.mjs permissions
node 1stbuddha.mjs guide
node 1stbuddha.mjs product antique-ayutthaya-buddha-statue-17th-century-museum-piece

The CLI returns JSON for product and discovery commands and Markdown for the guide. Failed requests exit with status 1 and print the server's recovery hint. No npm or PyPI release is currently published.

Versioning, limits and contact

The /api/v1/ path is the stable major version of the public adapter. Native Shopify customer GraphQL endpoints use dated Shopify API versions; follow the advertised discovery documents when upgrading. Public requests remain subject to Shopify and Cloudflare protections. Honor origin rate limits and Retry-After; there is no invented fixed quota.

For object research or commercial enquiries, use 1stBuddha contact. The product pages are the source for available pieces and their current offers.