SwagHQ APIswaghq.com ↗
Access SwagHQ's full product catalog via API: categories, brands, paginated collections, keyword search, and detailed product data with size inventory and tier pricing.
What is the SwagHQ API?
The SwagHQ API exposes 5 endpoints covering the complete swaghq.com promotional apparel and accessories catalog. Starting with list_categories and list_brands for navigation, you can feed collection IDs into list_products for paginated, filterable listings, run free-text queries via search_products, and pull full product detail — including quantity-tier pricing, per-size inventory, and logo decoration methods — through get_product.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/d420ec18-47a8-45a5-bb6d-8283e53b48a5/list_categories' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace swaghq-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: SwagHQ catalog SDK — browse categories, filter products, drill into detail."""
from parse_apis.swaghq_com_api import SwagHQ, ProductSort, ProductNotFound
client = SwagHQ()
# Browse the category tree and pick the first top-level department.
top_category = client.categories.list(limit=50).first()
if top_category is not None:
print(top_category.name, f"(id={top_category.collection_id})")
# List best-selling products in that category, capped at 5.
for product in top_category.products.list(sort=ProductSort.BEST_SELLER, limit=5):
print(product.name, f"${product.msrp}", product.sizes)
# Drill one summary into its full detail page.
summary = top_category.products.list(sort=ProductSort.BEST_SELLER, limit=1).first()
if summary is not None:
detail = summary.detail()
print(detail.name, detail.description_html[:80])
print("Colors:", [c.color for c in detail.colors])
print("Sizes in stock:", [inv.size for inv in detail.inventory if inv.in_stock > 0])
# Keyword search across the whole catalog.
hit = client.product_summaries.search(query="polo", limit=1).first()
if hit is not None:
full = hit.detail()
print(full.name, f"${full.sale_price}", full.decoration_methods)
if full.quantity_pricing:
print("Min order:", full.quantity_pricing.minimum_units)
# Point lookup by slug — with typed error handling.
try:
shirt = client.products.get(slug="does-not-exist-xyz")
except ProductNotFound:
print("Product not found — expected for an invalid slug.")
print("exercised: categories.list / category.products.list / product_summaries.search / summary.detail / products.get")
Returns the site's product category tree as a flat list (top-level departments such as Men, Women, Workwear, Headwear, Accessories and Best Seller, plus their sub-categories) with each entry's collection_id, slug, level and parent_collection_id. One request; no pagination. The collection_id values are the identifiers accepted by list_products with is_brand omitted or false.
No input parameters required.
{
"type": "object",
"fields": {
"count": "integer number of category entries returned",
"categories": "array of category entries: collection_id (integer key for list_products), name, slug (site URL path segment), parent_collection_id (null for top-level), level (0 = department, 1 = sub-category, 2 = leaf)"
},
"sample": {
"data": {
"count": 43,
"categories": [
{
"name": "Men",
"slug": "men",
"level": 0,
"collection_id": 1,
"parent_collection_id": null
},
{
"name": "Shirts",
"slug": "men/shirts",
"level": 1,
"collection_id": 16,
"parent_collection_id": 1
}
]
},
"status": "success"
}
}About the SwagHQ API
Navigation and Discovery
list_categories returns the full category tree as a flat list: each entry includes a collection_id, name, slug, level, and parent_collection_id. list_brands returns every brand in the site's Brands menu with its collection_id, name, slug, and logo_url. Both endpoints require no inputs and return in a single request. The collection_id values from either endpoint feed directly into list_products.
Browsing Collections
list_products accepts a required collection_id and an is_brand boolean to distinguish brand collections from category collections. Results are paginated at 12 products per page and can be filtered by color, size, and brand facets whose valid values are listed in the available_filters field of each response. Each product card in the products array includes product_id, slug, name, sku, brand, msrp, sale_price, low_price, color families, tags such as best seller, stock flags, and sibling color variant references. The response also echoes applied_filters, total, total_pages, and has_more.
Search
search_products accepts a free-text query and supports offset and limit (1–100) for pagination within the result set. The response includes a products array using the same card shape as list_products, a suggested_categories array of {collection_id, name, slug} objects usable directly with list_products, and is_truncated to signal when the site's match set exceeds what can be fully addressed.
Product Detail
get_product takes a slug exactly as emitted by list_products or search_products and returns the full product record: description HTML, msrp, sale_price, low_price, sizes, tags, per-size inventory, quantity-tier pricing table, logo decoration methods, and a colors array of sibling variants each with its own slug, image_url, and full images list. Fetching a different color requires a separate get_product call with that variant's slug.
The SwagHQ API is a managed, monitored endpoint for swaghq.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when swaghq.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official swaghq.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a branded merchandise storefront by syncing SwagHQ's category tree and product cards into your own catalog database.
- Automate quantity-tier price comparisons for corporate bulk apparel orders using the pricing table from
get_product. - Surface suggested category results alongside product hits in an in-app search experience using
suggested_categoriesfromsearch_products. - Monitor per-size inventory levels across color variants to alert procurement teams when popular SKUs run low.
- Populate a brand directory with logos and product counts by combining
list_brandswithlist_productsfiltered by brandcollection_id. - Generate decoration-method guides for a corporate gifting platform using the logo customization options returned by
get_product. - Filter collection pages by color family and size facets from
available_filtersto replicate SwagHQ's browse experience in a custom UI.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does SwagHQ have an official public developer API?+
How do color variants work across endpoints?+
list_products and search_products include sibling color references in each product card. get_product returns the full colors array with per-variant slug, image_url, and images list. To get complete detail for a different color of the same style, call get_product again with that variant's slug.What does `is_truncated` mean in `search_products` results?+
is_truncated is true, the site returned more matches than could be fully retrieved. Only the first retrieved products are addressable via offset and limit. The total field will be null in this case. Narrowing your query term typically reduces the result set to a fully addressable range.Does the API return customer reviews or product ratings?+
Can I filter `list_products` by multiple colors or sizes at once?+
color and a single size filter value drawn from available_filters. Multi-value filtering for the same facet is not supported in a single call. You can fork this API on Parse and revise the list_products endpoint to support multi-value facet filtering.