Developers

Upload art and place it on the BuyMeBlocks wall from your own code. Every amount is in credits. Requests are limited to 120 a minute per key, of which 20 may be uploads or placements.

The API opens at launch. You can create a key now; requests answer 404 until then.

Your API keys

Quick start

KEY=bmb_…   # from this page

# 1. Upload an image, then wait until it is APPROVED
curl -X POST https://buymeblocks.com/api/v1/artworks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: image/png" \
  --data-binary @art.png
curl https://buymeblocks.com/api/v1/artworks/$ARTWORK_ID -H "Authorization: Bearer $KEY"

# 2. Price a spot
curl -X POST https://buymeblocks.com/api/v1/quote \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"rects":[{"x":100,"y":100,"width":40,"height":40}]}'

# 3. Place it (never more than the quoted total)
curl -X POST https://buymeblocks.com/api/v1/placements \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"rects":[{"x":100,"y":100,"width":40,"height":40}],"artworkIds":["'$ARTWORK_ID'"],"maxTotal":"1600"}'

Every amount is in credits, as a decimal string. Areas are multiples of 10 pixels. Uploads follow the same content rules and screening as the website.

Reference

GET/api/v1/me: Your account and credits.
POST/api/v1/artworks: Upload an image. Send the image bytes as the body. Every upload is screened before it can be placed: poll its status until APPROVED.
GET/api/v1/artworks/{id}: An upload’s screening status.
POST/api/v1/quote: Price a spot. What placing on these rects would cost now. Every placement your rects touch is replaced whole, so they must cover all of it (otherwise 422 INCOMPLETE_GROUP_REPLACEMENT). Painting over protected art costs its unused protection, which goes to whoever paid for it. If a Protection shield guards one of them, the attempt is blocked, uses the shield up and costs only `challengeFee`.
POST/api/v1/placements: Place art. Places approved artwork, paying from your credits. Send maxTotal from a quote so a price rise is refused rather than paid.

Full contract: openapi.json (OpenAPI 3.1).