> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Hub API Overview

> REST endpoints for the Marketplace Hub — browse, preview, clone, subscribe, sync, and analyze published catalogs.

## Overview

The **Hub API** provides programmatic access to the Marketplace Hub — the B2B content exchange where workspaces publish and discover product catalogs. The API supports both consumer operations (browse, preview, clone, subscribe) and publisher operations (analytics, unpublish).

***

## Base URL

All Hub API endpoints use the following base:

```
https://app.alana.shopping/api/hub/
```

***

## Endpoint groups

<CardGroup cols={2}>
  <Card title="Browse Catalogs" icon="search" href="/api-reference/hub/browse-catalogs">
    `GET /hub/catalogs` — search and filter the public Hub feed
  </Card>

  <Card title="Preview" icon="eye" href="/api-reference/hub/preview">
    `GET /hub/catalogs/{id}/preview` — first 10 products + stats, no clone required
  </Card>

  <Card title="Clone & Subscribe" icon="copy" href="/api-reference/hub/clone-subscribe">
    `POST /hub/catalogs/{id}/clone` and `/subscribe` — acquire catalog access
  </Card>

  <Card title="Sync & Conflicts" icon="refresh" href="/api-reference/hub/sync-conflicts">
    Subscription sync management and conflict resolution
  </Card>

  <Card title="Publisher Analytics" icon="chart-bar" href="/api-reference/hub/publisher-analytics">
    `GET /hub/catalogs/{id}/analytics` — views, clones, subscribers, revenue
  </Card>
</CardGroup>

***

## Authentication

### Public endpoints (no auth required)

The following endpoints are publicly accessible without authentication:

| Endpoint                                    | Description                 |
| ------------------------------------------- | --------------------------- |
| `GET /api/hub/catalogs`                     | Browse the public Hub feed  |
| `GET /api/hub/catalogs/{catalogId}/preview` | Preview a published catalog |

### Authenticated endpoints

All other endpoints require a Bearer token:

```
Authorization: Bearer sk_live_your_api_key_here
```

Write operations (clone, subscribe, analytics) require the API key to belong to a workspace with an active plan.

***

## Rate limits

| Tier            | Public endpoints   | Authenticated endpoints |
| --------------- | ------------------ | ----------------------- |
| Unauthenticated | 60 requests/minute | —                       |
| Free            | 60 requests/minute | 60 requests/minute      |
| Pro             | 60 requests/minute | 300 requests/minute     |
| Business        | 60 requests/minute | 600 requests/minute     |
| Enterprise      | Custom             | Custom                  |

Rate limit headers are included in every response:

```
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 294
X-RateLimit-Reset: 1742300400
```

When the limit is exceeded, a 429 response is returned with a `Retry-After` header.

***

## HubCatalog object

The core object returned by Hub browse and preview endpoints:

```json theme={null}
{
  "id": "hub_cat_9x8k2m",
  "name": "Spring 2026 Apparel",
  "description": "500+ SKUs of curated spring apparel from top European brands.",
  "publisher": {
    "workspaceId": "ws_abc",
    "displayName": "EuroFashion Wholesale",
    "verified": true
  },
  "productCount": 512,
  "price": {
    "model": "free"
  },
  "category": "apparel",
  "tags": ["spring", "2026", "european"],
  "score": 78,
  "subscribers": 34,
  "publishedAt": "2026-02-01T09:00:00Z",
  "lastUpdatedAt": "2026-03-10T14:30:00Z",
  "version": 5
}
```

***

## Error responses

All Hub endpoints return standard error shapes:

```json theme={null}
{
  "error": {
    "code": "CATALOG_NOT_FOUND",
    "message": "Catalog hub_cat_xyz does not exist or has been unpublished",
    "details": null
  }
}
```

Common error codes:

| Code                       | HTTP status | Description                                                          |
| -------------------------- | ----------- | -------------------------------------------------------------------- |
| `CATALOG_NOT_FOUND`        | 404         | Hub catalog ID not found or unpublished                              |
| `CATALOG_PRIVATE`          | 404         | Catalog exists but is private (returned as 404 to avoid enumeration) |
| `ALREADY_SUBSCRIBED`       | 409         | Workspace already has an active subscription to this catalog         |
| `PAYMENT_REQUIRED`         | 402         | Paid catalog — complete Stripe Checkout before cloning/subscribing   |
| `INSUFFICIENT_PERMISSIONS` | 403         | Operation not permitted for this API key                             |
| `RATE_LIMIT_EXCEEDED`      | 429         | Too many requests — see `Retry-After` header                         |