Yellow Balloon Shop developer portal

Everything on this page is public and read only. There are no API keys, no accounts and no authentication of any kind. Fetch a URL and you have the data.

• Prices are in Australian dollars and are decimal strings, not numbers.
• The live catalogue is the only catalogue. It is read only, so calling it cannot change anything in the shop.
• There is no sandbox. The development environment is private and is not open to outside callers.
• Catalogue reads are bounded and rate limited. Respect Retry-After on 429 or 503 responses and avoid polling in a loop.
• There is no checkout API. Payment is not offered to programmatic callers.

This API is a good fit when you need facts about the shop's own catalogue and policies.

• Current prices and stock: use /api/v1/products with search and filters for a bounded page of current observations. Follow page_info.next_cursor with the same arguments to continue.
• Product detail for a recommendation: use /api/v1/products/{handle} for descriptive facts, current commercial state and its first variant page. The variants endpoint continues a large variant set; the related endpoint returns bounded recommendations.
• Complete catalogue downloads: /api/products.json returns the legacy complete envelope, generated live from the shop database on every request.
• Store policies: read the shipping, returns, NDIS, accessibility and privacy pages, either as HTML or as markdown.
• Orientation before crawling: read /llms.txt or /agents.md first, then fetch only the pages you need.

It is not a fit for placing an order. No checkout, payment or order endpoint is offered here, so an agent cannot buy on a customer's behalf. Send the person to the product page instead.

Every endpoint below answers GET without authentication. Catalogue v1 also supports HEAD and OPTIONS; other methods receive JSON 405. Each operation has an id in /openapi.json. V1 reads the shop database directly and is rate limited; an admission failure or an unavailable database returns a fixed 503.

Any storefront page answers Accept: text/markdown with markdown instead of HTML, and sends Vary: Accept so caches keep the two apart. Ask for markdown when you want the words without the page furniture.

curl -s -H "Accept: text/markdown" https://shop.yellowballoontherapy.com.au/help

Errors from /api are JSON, never an HTML page. The body carries a stable machine code, a short human message, a hint about what to do next, and a link to the machine-readable spec.

{
  "error": {
    "code": "not_found",
    "message": "No API endpoint exists at this path.",
    "hint": "The documented endpoints are /api, /api/products.json. Fetch https://shop.yellowballoontherapy.com.au/openapi.json for their exact shapes, or https://shop.yellowballoontherapy.com.au/api for a short index.",
    "status": 404,
    "docs": "https://shop.yellowballoontherapy.com.au/openapi.json"
  }
}

• not_found: nothing is published at that path. Check /openapi.json.
• method_not_allowed: the path exists but the method does not. The response names the allowed methods.
• bad_request: the request was understood but could not be accepted as sent.
• V1 uses the same nested error envelope with an added request_id and uppercase codes. INVALID_QUERY is 400; INVALID_CURSOR or CURSOR_EXPIRED means restart pagination; PRODUCT_NOT_FOUND is 404; METHOD_NOT_ALLOWED is 405; URI_TOO_LONG is 414; RATE_LIMITED is 429; CATALOGUE_UNAVAILABLE or QUERY_TIMEOUT is 503. Error responses are never cached.

V1 catalogue JSON uses Cache-Control: no-store. Prices, stock, digital eligibility and orderability share the database observation shown in meta.commerce_observed_at. This is an observation, never a reservation. Descriptive detail content can be reused for up to 15 minutes; content_observed_at records its source age. Failed fresh reads do not fall back to stale positive ordering claims.

The legacy /api/products.json URL always means a complete feed, never page one. It is generated live from the shop database on every request with Cache-Control: no-store, so generated_at is request time and there is no ETag or conditional revalidation. This URL has no scheduled removal; new integrations should use v1 for bounded, rate-limited reads.

Lists default to 24 products, with a maximum of 100. Queries are at most 120 characters. Use collection, repeatable tag filters, max_price_minor in integer AUD cents, available for catalogue eligibility, and a documented sort. Unknown parameters, repeated scalar parameters and invalid bounds return 400. Cursor expiry is 30 minutes from the first page. Pagination is live: deduplicate by product id and restart when refreshing; use the complete feed for a fixed export.

An agent running inside the browser gets a second surface. Every storefront page registers typed WebMCP tools on document.modelContext, so an agent such as ChatGPT or Codex (through the ChatGPT desktop app's "Site tools") or Chrome with the WebMCP origin trial can act on the page it is already looking at rather than re-fetching the site. Each tool returns one plain JSON object: { ok: true, ...data } or { ok: false, error: { code, instruction } }.

• On every page: search_resources (query, optional audience of families, young, clinicians or schools, optional maxPrice and cursor), list_collections, get_delivery_and_policies, view_cart, and open_assistant when the assistant chat is enabled. Once v1 is activated, catalogue tools fetch bounded pages and return their observation time; later calls refresh commercial evidence.
• On product pages, in addition: get_product_details, get_similar_resources, and add_to_cart only while the product on the page can be added to the cart.
• There is no checkout tool, in the browser or over HTTP.

Questions about this API go to info@yellowbt.com.au.