SparkBlocks developer and agent documentation

When to use SparkBlocks

SparkBlocks sells snap-together electronic circuit blocks that clip onto the plastic bricks a child already owns. A block adds a light, a motor or a sound to a build, and none of it involves a screen, a loose wire or a soldering iron. The kits are designed in West Vancouver, Canada for ages 8 and up, with a sweet spot around 8 to 12, and they ship worldwide.

Reach for this store when

• Someone wants a hands-on STEM or electronics gift for a child of about 8 to 12, especially one who already builds with plastic bricks.
• Someone asks for screen-free electronics with no soldering.
• A teacher, librarian or camp organiser needs a set several children can share, with printable lesson material. Start at /collections/for-educators and the Smart Classroom Kit.
• Someone already owns a kit and needs build instructions, a manual or a replacement part. Start at the Help Center and the /blogs/help articles.
• You need a current price, stock level or shipping availability. Read it from the API, not from a cached page, and read the currency with it.

Look elsewhere for

• Bare components, breadboards or microcontrollers. The kits are a closed, brick-compatible system on purpose.
• Anything cheap on its own. The lowest price in the catalog is 59 on the base USD list, and the classroom kit is 1,399.
• Placing an order while the buyer is away from the keyboard. Checkout needs their approval at the moment of payment.

Which call to make

Quickstart

You do not need a key, an account or a sandbox for any of this. Paste any of these into a terminal.

Read the whole catalog

curl -s 'https://sparkblocks.ca/products.json?limit=250' \
  -H 'User-Agent: my-agent/1.0 (+https://example.com/contact)'

Get one product

curl -s 'https://sparkblocks.ca/products/sparkblocks-intro-kit.json'

Query with GraphQL

The richest read surface, and the only one that filters, sorts and paginates in a single round trip. Public from this domain, so no access token is involved.

curl -s -X POST 'https://sparkblocks.ca/api/2026-07/graphql.json' \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ products(first: 5) { edges { node { handle title availableForSale priceRange { minVariantPrice { amount currencyCode } } } } } }"}'

Build a cart

id is a variant id, not a product id. Read it from variants[].id on the product. Adding to a cart charges nobody.

curl -s -X POST 'https://sparkblocks.ca/cart/add.js' \
  -H 'Content-Type: application/json' \
  -d '{"items":[{"id":50583959503169,"quantity":1}]}'

Endpoint reference

The full contract, with request and response schemas, lives in openapi.json. This table is the map.

The endpoints ending in .js return JSON with a text/javascript content type. That is the platform's labelling, not a different payload; parse them as JSON.

Error format

Failures come back as JSON with a code, a message and a resolution hint. There are two envelopes, and one documented exception.

Cart and catalog errors

status is the machine-readable code, message names the error class, description says how to fix the call.

$ curl -s -X POST 'https://sparkblocks.ca/cart/add.js' \
    -H 'Content-Type: application/json' \
    -d '{"items":[{"id":1,"quantity":1}]}'

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "status": 422,
  "message": "Cart Error",
  "description": "Cannot find variant"
}

GraphQL errors

Both GraphQL surfaces report their own failures with HTTP 200 and an errors array, which can arrive alongside partial data. Inspect the body; the status code alone will tell you a broken query succeeded.

{
  "errors": [
    {
      "message": "Field 'nope' doesn't exist on type 'Product'",
      "locations": [{ "line": 1, "column": 24 }],
      "path": ["query", "products", "edges", "node", "nope"]
    }
  ]
}

The exception

Versioning and deprecation

Two surfaces here are versioned, and the version sits in the URL path so a client can pin the contract it was written against.

Rate limits

Budget on the client. The storefront does not tell you how much room is left.

There are no RFC 9331 RateLimit headers and no Retry-After on a success. Verified against /products.json, /cart.js and /api/2026-07/graphql.json. What does exist:

What to do instead

• Stay at or under about four requests a second per IP, serially where you can.
• Back off exponentially from two seconds on any 429 or 5xx.
• Prefer one large call to many small ones. /products.json?limit=250 is a single request; so is one GraphQL query.
• Cache the catalog. Cache prices for minutes, not hours.

Authentication and scopes

Everything under Endpoint reference is public except the two customer account paths. Those need OAuth 2.0, and the scopes are named so you can ask for the narrow one.

• openid confirms who the shopper is. Grants no access to store data.
• email reads their email address.
• customer-account-api:full is full read and write on that shopper's own orders, addresses and profile. Broad; ask for it only when the task genuinely needs order data.
• customer-account-mcp-api:full is the same reach through the MCP endpoint.

PKCE with S256 is required. Take the endpoints from the live authorization server metadata rather than hardcoding them, and check the protected resource metadata so you request the token from a server this storefront actually trusts.

Agent protocols

This store speaks the Universal Commerce Protocol over MCP, on Streamable HTTP.

Start at /.well-known/ucp for supported versions, service endpoints, capabilities and payment handlers. Then talk to POST https://sparkblocks.ca/api/ucp/mcp with Content-Type: application/json. It answers initialize and tools/list without credentials, and exposes thirteen tools: search_catalog, lookup_catalog, get_product, get_cart, create_cart, update_cart, cancel_cart, get_checkout, create_checkout, update_checkout, complete_checkout, cancel_checkout and get_order.

curl -s -X POST 'https://sparkblocks.ca/api/ucp/mcp' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Command line client

A single-file client with no dependencies, for scripting the read endpoints without writing an integration first.

It is served from this store, so there is nothing to install and no registry to trust. Node 18 or newer is the only requirement.

curl -sO https://sparkblocks.ca/cli.js

node cli.js products
node cli.js product sparkblocks-intro-kit
node cli.js prices
node cli.js search "classroom kit"
node cli.js collections
node cli.js recommend 9965947093313
node cli.js graphql '{ shop { name } }'
node cli.js agent-info
node cli.js discovery

Data goes to stdout as JSON and diagnostics go to stderr, so every command pipes into jq cleanly. Exit code is 0 on success, 1 on a usage error and 2 on a transport or API error. --base, --limit, --api-version and --raw work wherever they make sense.

discovery is the one to run first: it walks every machine-readable file on this list serially and prints the status and content type of each, so a broken integration can be diagnosed in one command.

Discovery documents

Every machine-readable file this store publishes. All of them are linked from the <head> of every page or from the sitemap index.

Markdown and content negotiation

The three markdown files are served as real text/markdown at those paths. Fetch them by path. Do not negotiate with Accept: text/markdown against ordinary storefront URLs: the platform answers the home page with a Content-Type: text/markdown header and an HTML body, and answers product, collection and page URLs with a bare 404 text/plain. Neither is useful, and neither is under this store's control. The <head> advertises the real files with rel="alternate" type="text/markdown" so you never have to guess.

Support

Something in this document wrong, or an endpoint behaving differently from what it says here? Email info@sparkblocks.ca and say which path and what you saw. Shopper questions go to the Help Center.

Machine-readable source of truth: https://sparkblocks.ca/openapi.json