Developer API

Creates an Aeroblox account and enrols it in your organization. The organization comes from your API key and is never read from the request, so you cannot create end users anywhere but your own org.

curl -X POST https://aeroblox-api-eight.vercel.app/api/public/v1/auth/register \
  -H "Authorization: Bearer $AEROBLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "a-real-password",
    "firstName": "Ada"
  }'

Response — 201

{
  "endUser": {
    "id": "d7930066-7406-42ba-8a4f-ea4ac0aea23a",
    "email": "user@example.com",
    "buyerId": "cmtjcr591000hk5sji41g5u3o",
    "firstName": "Ada",
    "lastName": null
  },
  "session": {
    "accessToken": "eyJhbGciOiJFUzI1NiIs...",
    "refreshToken": "ufs5ktvuehv3...",
    "expiresIn": 3600,
    "expiresAt": 1788312118,
    "tokenType": "bearer"
  }
}

endUser.id is the Aeroblox account, stable everywhere. endUser.buyerId is that person's ownership record inside your organization — it is what asset ownership will point at.

An email that already has an Aeroblox account returns 409 conflict. Send those users to login instead: adopting an existing account without checking its password would let any app enrol a stranger's identity.

Accounts are created already confirmed. Aeroblox sends no verification mail for your users — that relationship is yours, so verify on your side if you need to.

Returns a fresh session. This also enrols existing Aeroblox users into your organization on their first successful sign-in, so a person can carry one Aeroblox identity across every app built on this API.

curl -X POST https://aeroblox-api-eight.vercel.app/api/public/v1/auth/login \
  -H "Authorization: Bearer $AEROBLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com", "password": "a-real-password" }'

The response is the same shape as register. Wrong credentials return 401 unauthorized with a deliberately vague message — the endpoint will not tell a caller whether an email is registered.

Every asset in your organization's library. Returns finished assets by default and hides archived ones, along with the interior pages of flipbooks, which belong to their edition rather than standing alone as catalogue entries.

curl "https://aeroblox-api-eight.vercel.app/api/public/v1/assets?publisher=Aeroblox&limit=25" \
  -H "Authorization: Bearer $AEROBLOX_API_KEY"

Response — 200

{
  "assets": [
    {
      "id": "cmt91slkg0001l704u83sqldg",
      "title": "Bell Rock",
      "description": null,
      "assetType": "single",
      "status": "ready",
      "publisher": "Aeroblox",
      "creators": ["Dogma"],
      "lid": "AB-MI87BSM7",
      "imageUrl": "https://.../bell-rock.png",
      "ipfs":   { "assetCid": null, "metadataCid": null },
      "hedera": { "tokenId": null, "serial": null },
      "createdAt": "2026-08-25T19:18:27.376Z"
    }
  ],
  "nextCursor": "cmt5c9i270001jr04vs7oql2y"
}

Page by passing nextCursor back as cursor. A null cursor means you have reached the end.

A note on publishers. The publisher is free text captured when an asset was imported, so “Aeroblox” and “Aeroblox Inc” are two different publishers as far as the data is concerned. Use publisher when you know the exact name and publisherContains when you are matching loosely.

imageUrl is a permanent IPFS gateway URL for pinned assets, and a signed URL valid for one hour otherwise. Do not store it — re-read it when you need it.

Gives an asset to an end user with no sale involved — the asset your application just decided to hand someone. Authenticated by your API key alone, with no end-user token: your server is the authority on who receives it, and an end user must never be able to grant themselves anything.

What happens depends on the asset

A flipbook edition issues the recipient their own copy. The master stays in your library, and the end user receives an individual copy with its own LID derived from the edition, its own watermarked cover and its own signed manifest — so a thousand end users can receive the same asset and each hold a provably distinct one. Each copy is an encode job, billed as ldpe_encoding rather than against your API allocation.

A single asset transfers outright. One asset, one owner, so it can be granted exactly once — granting it again returns 409 conflict and the current owner keeps it.

curl -X POST https://aeroblox-api-eight.vercel.app/api/public/v1/assets/$ASSET_ID/grant \
  -H "Authorization: Bearer $AEROBLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "buyerId": "cmtjcr591000hk5sji41g5u3o" }'

Response — 201, single asset

{
  "kind": "asset_transfer",
  "asset": { "id": "cmt...", "title": "Collector Card", "assetType": "single", "status": "ready" }
}

Response — 201, flipbook edition

{
  "kind": "edition_copy",
  "copy": {
    "id": "cmt...",
    "editionAssetId": "cmt...",
    "copyNumber": 7,
    "lid": "3f2a...-uuid",
    "status": "issued",
    "coverCid": "bafy...",
    "manifestCid": "bafy...",
    "hederaTokenId": null,
    "hederaSerial": null,
    "issuedAt": "2026-09-01T12:00:00.000Z"
  }
}

With mint: true, a mint that fails comes back as a mintError field alongside the copy. The copy is still validly issued — only the on-chain serial is missing.

An asset with an active marketplace listing cannot be granted: cancel the listing first, or the sale would be left pointing at something that moved.

Everything the signed-in end user owns in your organization. Requires both credentials — your API key and their X-End-User-Token — and is scoped to that end user, so it can only ever return their own holdings.

An end user can hold two different kinds of thing and an inventory screen wants both, so they arrive in one list, newest first, tagged by kind: asset for something owned outright, copy for one copy of a flipbook edition.

curl https://aeroblox-api-eight.vercel.app/api/public/v1/me/assets \
  -H "Authorization: Bearer $AEROBLOX_API_KEY" \
  -H "X-End-User-Token: $END_USER_ACCESS_TOKEN"

{
  "items": [
    {
      "kind": "copy",
      "id": "cmt...",
      "editionAssetId": "cmt...",
      "title": "Volume One",
      "copyNumber": 7,
      "lid": "3f2a...-uuid",
      "imageUrl": "https://.../bafy...",
      "hedera": { "tokenId": null, "serial": null },
      "acquiredAt": "2026-09-01T12:00:00.000Z"
    },
    {
      "kind": "asset",
      "id": "cmt...",
      "title": "Collector Card",
      "assetType": "single",
      "publisher": "Meridian Press",
      "imageUrl": "https://.../collector-card.png",
      "acquiredAt": "2026-08-30T09:00:00.000Z"
    }
  ]
}

A copy's imageUrl is that copy's own watermarked cover, not the edition's — two end users holding copies of the same book see different images.

Every asset currently for sale in your organization, whoever owns it. This is the feed behind an in-app marketplace: organization-listed items and end-user-listed items arrive together.

Scoped to your organization, unlike the Aeroblox portal's own marketplace, which is deliberately cross-org. Your end users see your market, not unrelated organizations'.

curl "https://aeroblox-api-eight.vercel.app/api/public/v1/listings?sort=price_asc" \
  -H "Authorization: Bearer $AEROBLOX_API_KEY"

{
  "listings": [
    {
      "id": "cmt...",
      "amountCents": 2500,
      "currency": "usd",
      "listedAt": "2026-09-01T10:00:00.000Z",
      "seller": { "id": "cmt...", "displayName": "Meridian Press" },
      "asset": {
        "id": "cmt...",
        "title": "On Sale",
        "assetType": "single",
        "publisher": "Meridian Press",
        "imageUrl": "https://.../on-sale.png",
        "hedera": { "tokenId": null, "serial": null }
      }
    }
  ],
  "nextCursor": null
}

Puts an end user's item up for sale. Needs their X-End-User-Token: ownership is the gate, and inside one organization the developer's stock and every end user's assets share a library — so an end user can list only what they actually own.

curl -X POST https://aeroblox-api-eight.vercel.app/api/public/v1/me/listings \
  -H "Authorization: Bearer $AEROBLOX_API_KEY" \
  -H "X-End-User-Token: $END_USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "assetId": "cmt...", "amountCents": 2499 }'

End users do not need a Stripe account. Sale proceeds go to your organization, not to them — see below — so nobody is put through identity verification to sell a asset.

GET /me/listings returns that end user's own listings, and DELETE /me/listings/:id takes one down. A listing that already sold stays sold.

Returns a Stripe-hosted checkout URL. Send the end user there; nothing changes hands until Stripe confirms payment. Needs the buyer's X-End-User-Token, because the item lands in that person's inventory.

curl -X POST https://aeroblox-api-eight.vercel.app/api/public/v1/listings/$LISTING_ID/checkout \
  -H "Authorization: Bearer $AEROBLOX_API_KEY" \
  -H "X-End-User-Token: $BUYER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "successUrl": "https://yourapplication.example/bought",
        "cancelUrl":  "https://yourapplication.example/shop" }'

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/cs_test_...",
  "saleId": "cmt...",
  "amountCents": 2499
}

When payment completes, ownership moves automatically and the listing is marked sold. An end user cannot buy their own listing, and an abandoned checkout expires after 30 minutes leaving the item still for sale.

Sales you have not yet credited — a work queue. Pass ?credited=all for full history or ?credited=true for what you have settled.

{
  "sales": [
    {
      "id": "cmt...",
      "status": "paid",
      "sellerBuyerId": "cmt...",     // credit this end user
      "buyerBuyerId": "cmt...",
      "amountCents": 2499,
      "sellerCents": 2170,           // with this much
      "estimated": {
        "developerCents": 190,          // your cut
        "aerobloxCents": 37,
        "stripeFeeCents": 102
      },
      "creditedAt": null,
      "paidAt": "2026-09-03T00:50:00.000Z"
    }
  ],
  "nextCursor": null
}

sellerCents is exact. The estimated block is not: Stripe's real fee depends on the card and is only known from the balance transaction after settlement, so treat those as the intended split rather than settled figures.

Call this after the credit lands in your economy, to drop the sale from the queue. Already-credited sales return their existing timestamp rather than an error, because a retry is the expected shape of this call.

If your credit write succeeds and this call fails, the sale simply reappears on your next poll — so make your own crediting idempotent, keyed on the sale id.

Embeds an Aeroblox provenance watermark into an image and returns the watermarked bytes. Stateless: no library asset is created, nothing is written to storage, nothing is persisted. That is what makes it usable from a script or an MCP client with no library to manage first.

Two different things come back

lid is provenance the encoder mints and owns — 32 hex with a CRC. Pass it back as lid on a later encode to keep the same provenance across a re-encode. payload is a string yousupply, embedded in the file-domain channel, and is what /decodehands back. Omit it and the image still gets an lid; it just carries nothing of yours.

curl -X POST https://aeroblox-api-eight.vercel.app/api/public/v1/encode \
  -H "Authorization: Bearer $AEROBLOX_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"image\": \"$(base64 -i cover.png)\", \"payload\": \"catalogue-01\" }"

{
  "lid": "9f3a1c...",
  "payload": "catalogue-01",
  "channel": "ming",
  "image": "iVBORw0KGgo...",
  "metrics": { "psnr": null, "delta": null, "tier": 3 }
}

The watermark is imperceptible — the returned image looks identical to the one you sent. q1, the cam-oriented channel, is deliberately not offered here: it is reserved for tickets a gate camera must read, and spending it would mean a louder, more visible embed for callers who are not photographing anything.

Images ride inline as base64, so the JSON body is capped at 4 MB — roughly a 3 MB image. Anything larger belongs in the portal's library instead.

Reads a watermark back out of an image and returns what was embedded. Two independent questions are answered, and the response keeps them separate.

Verification asks whether a genuine Aeroblox watermark was recovered from the pixels. It fails closed: a code is never read from your request, so you cannot assert one the image did not carry. A failure is a 422.

Recognition asks whether that identifier matches an asset in the Aeroblox library. A verified image with no matching asset returns asset: null with a 200 — a successful decode, not a failure. Everything encoded through /encode lands in exactly this state, because that endpoint creates no asset.

{
  "verified": true,
  "payload": "catalogue-01",
  "channels": { "q1": null, "ming": "catalogue-01", "b1": null },
  "asset": null,
  "stats": { "decodeErr": 0, "pilotCalBer": 0, "pilotSnr": 0 }
}

There is no lid in a decode response, and that is deliberate. /encode returns an encoder-minted provenance lid; the only thing recoverable from the pixels is the payload above. Calling both “lid” would invite mistaking one for the other.

What this does not prove

The watermark is unsigned, so a recovered code attests that this image carries this code — not that the image is genuine. Anyone who can read a code off a real asset can embed it in a forgery and be recognized here. Closing that needs a signature over the asset identity and content digest, verified at decode time, and is tracked separately.

A decode also fails when the mark has been destroyed rather than never applied — re-compression, cropping and resizing all degrade it. A 422 means “no watermark recoverable”, not “never encoded”.

Free copies currently on offer in your organization. Exhausted and cancelled ones are hidden unless you pass includeClosed=true.

Send an end-user token alongside your key and each row gains claimed_by_you. Without one it is null — unknown, not false, which matters: showing a claim button to someone who already holds a copy is worse than showing nothing.

{
  "giveaways": [
    {
      "id": "cmt...",
      "status": "active",
      "quantity": 100,
      "claimed": 37,
      "remaining": 63,
      "mints": true,
      "claimed_by_you": false,
      "asset": { "id": "cmt...", "title": "Volume One", "assetType": "flipbook", "imageUrl": "https://..." }
    }
  ],
  "nextCursor": null
}

claimed counts reserved slots, which includes copies still being produced — so claimed can exceed the number of finished copies for a minute or two.

Takes one copy for the end user named by X-End-User-Token. Needs both credentials — the key says which application, the token says which person — because “one per person” is only meaningful if we know who is asking.

Answers 202, not 200

The slot is taken immediately and durably; the copy is produced by a background job. That is the contract, not an implementation detail leaking out: producing a copy means an encode, two IPFS pins, a manifest signature and a mint. Blocking the claimant on all of that would risk handing them a timeout and losing them their place.

curl -X POST https://aeroblox-api-eight.vercel.app/api/public/v1/giveaways/$GIVEAWAY_ID/claim \
  -H "Authorization: Bearer $AEROBLOX_API_KEY" \
  -H "X-End-User-Token: $END_USER_ACCESS_TOKEN"

{
  "claimId": "cmt...",
  "status": "pending",
  "queued": true,
  "message": "Your free copy is reserved and is being produced."
}

Two different 409s, and a client should branch on error.reason rather than the message: exhausted means every copy has gone, and already_claimed means this person already has one. One per person is enforced by a database constraint, not an application check.

The other half of that 202. Scoped to the claimant — a claim belonging to someone else is indistinguishable from one that does not exist.

{
  "claimId": "cmt...",
  "status": "issued",
  "copy": {
    "copyNumber": 38,
    "lid": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
    "coverUrl": "https://.../bafy...",
    "hedera": { "tokenId": "0.0.12345", "serial": 38, "mintedAt": "2026-10-09T..." },
    "minted": true
  },
  "asset": null
}

A copy that is issued with no serial is still genuinely owned — it has its LID, cover and signed manifest, and can be minted later. That is reported as a successful claim rather than a failure, because it is one.