Developer access | StickerHub

01 / Quick start

Quick start

The StickerHub API issues one server-side API key per approved integration and serves public catalog data from the current site's /api/v1 paths.

Get an API key

Obtain a client key from the service administrator. It is completely separate from the Turso database token.

Send the header

Send X-API-Key with every request. Never place the key in public frontend code.

Continue the cursor

List responses return nextCursor. Pass it back unchanged; do not parse or display it.

One credential per integration

StickerHub operators create an API key for each approved integration, with its own rate limit, expiry, and revocation status. Anonymous self-service registration is not available; request access and receive the one-time key through a secure channel.

Your first request

Call the authenticated health endpoint first to confirm both the credential and catalog connection work.

Shell

curl https://stickerhub.lius.me/api/v1/health \
  -H 'X-API-Key: YOUR_API_KEY' \
  -H 'Accept: application/json'

02 / Authentication

Authentication

All five endpoints require an API key. A missing or invalid key returns 401; excessive traffic returns 429. The health endpoint is authenticated as well, so it can verify both service availability and client credentials.

Keep the key on your server.

Send the issued API key in the X-API-Key header. Do not place it in public browser code or commit it to a repository.

03 / Pagination and errors

Cursor pagination

Collection endpoints return a data array and a nullable nextCursor. Pass that cursor unchanged on the next request. The default page size is 24, and the accepted range is 1 through 50. Cursors are opaque; clients should never parse them or display them as user-facing page numbers.

Common status codes

HTTP	Common status codes
400	Invalid request parameters
401	Missing or invalid API key
404	Resource not found
429	Rate limit exceeded
500	The service could not complete the request

JavaScript example

Every error uses one safe envelope: error.code for program logic and error.message for people. Raw server exceptions are never returned.

JavaScript

const response = await fetch('/api/v1/albums?q=cat&limit=24', {
  headers: {
    Accept: 'application/json',
    'X-API-Key': process.env.STICKERHUB_API_KEY,
  },
})

if (!response.ok) {
  const { error } = await response.json()
  throw new Error(error.code + ': ' + error.message)
}

const { data, nextCursor } = await response.json()

04 / Resources and boundaries

Resource map

GET/api/v1/health

Health

Verify the API key and service connection.

GET/api/v1/albums

Albums

Search, paginate and read public sticker pack metadata.

GET/api/v1/members/{md5}

Members

List or read safe sticker member metadata by MD5.

Public data boundary

The API never returns aes_key, encrypt_url, raw_json, database credentials or source-tracking fields. Pack names, creators and descriptions remain in their original catalog language.