UnboxBridge API

Read-only REST API for accessing your manuals, scans, help requests, and revenue attribution data. Pro plan only

Base URL: https://app.unboxbridge.com/api/v1
Format: JSON, snake_case fields
Rate limit: 600 requests per minute per key
Auth: Bearer token in Authorization header

Authentication

Every request requires a bearer token. Generate keys at /app/api-keys in your embedded admin. The full key is shown once at creation time — copy it to your secret store before navigating away.

curl https://app.unboxbridge.com/api/v1/me \
  -H "Authorization: Bearer ub_YourSecretKeyHere"

Keys start with the ub_ prefix. The first 11 characters (ub_xxxxxxxx) are surfaced in the admin UI for identification; the remainder is the secret.

Errors

Status	Code	Meaning
401	`unauthorized`	Missing, malformed, or revoked key
403	`plan_required`	Shop is no longer on the Pro plan
404	`not_found`	Resource not found (or not owned by this shop)
400	`invalid_date`	Malformed `from` or `to` query parameter
429	`rate_limited`	Per-key throttle exceeded. See `Retry-After` header.

Pagination

List endpoints accept limit (default 25, max 100) and cursor query parameters. The response envelope is:

{
  "data": [ ... ],
  "meta": {
    "limit": 25,
    "has_more": true,
    "next_cursor": "Y2x4ZG..."
  }
}

To fetch the next page, pass cursor=<meta.next_cursor>. Cursors are opaque — do not parse them.

Endpoints

GET/api/v1/me

Returns the authenticated shop, plan, and key metadata. Useful as a connection smoke test.

{
  "data": {
    "shop": { "id": "...", "domain": "store.myshopify.com", "name": "Acme", "plan": "pro" },
    "api_key": { "id": "...", "name": "Zapier", "prefix": "ub_abcd1234", "scopes": ["read:all"], "created_at": "...", "last_used_at": "..." }
  }
}

GET/api/v1/manuals

Paginated list of manuals. Sort order: newest first.

Query: cursor, limit

GET/api/v1/manuals/:id

Detailed manual view including all language variants and their step content.

GET/api/v1/scans

Paginated QR scans. Raw IP + user agent are omitted; only coarse device / country / city / referer are returned.

Query: manualId, from (ISO date), to (ISO date), cursor, limit

GET/api/v1/help-requests

Paginated "I'm Stuck" submissions from your customers.

Query: manualId, resolved (true/false), from, to, cursor, limit

GET/api/v1/analytics/summary

Aggregate KPIs for the window: scan totals, engagement counts, help-request counts, attributed revenue.

Query: from, to

{
  "data": {
    "window": { "from": "2026-05-01T00:00:00.000Z", "to": "2026-05-31T23:59:59.000Z" },
    "scans": { "total": 142, "pdf_opened": 81, "video_played": 53, "engagement_rate": 0.9437 },
    "help_requests": { "total": 7, "unresolved": 2 },
    "attribution": { "order_count": 4, "revenue_total": 287.45 }
  }
}

Versioning

All endpoints are under /api/v1/. Breaking changes will go to /api/v2/; non-breaking additions (new fields, new optional query params) are made in place. Subscribe to the changelog for advance notice.