{"openapi":"3.0.3","info":{"title":"Target API (ReefAPI)","version":"1.0.1","description":"Target API — search or browse the target.com (US) catalogue and pull one product in full: the UPC barcode, shipping weight and package dimensions, the complete image gallery, the whole colour/size variant matrix with each variant's own price, stock and native Target id, the specification table, brand, availability, star rating with its full distribution, and customer reviews inline — one call, no API key, account or cookie required Call POST /target/v1/{action} with an x-api-key header; every response is the { ok, data, meta, error } envelope.","contact":{"name":"ReefAPI","url":"https://reefapi.com/target-api","email":"support@reefapi.com"},"license":{"name":"ReefAPI Terms","url":"https://reefapi.com/terms"},"termsOfService":"https://reefapi.com/terms"},"externalDocs":{"description":"Target API documentation","url":"https://reefapi.com/docs/target"},"servers":[{"url":"https://api.reefapi.com"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"target","description":"Target API — search or browse the target.com (US) catalogue and pull one product in full: the UPC barcode, shipping weight and package dimensions, the complete image gallery, the whole colour/size variant matrix with each variant's own price, stock and native Target id, the specification table, brand, availability, star rating with its full distribution, and customer reviews inline — one call, no API key, account or cookie required"}],"paths":{"/target/v1/search":{"post":{"operationId":"target_search","summary":"Find products on target.com (US)","description":"Find products on target.com (US). Give a free-text `query` ('coffee maker', 'lego star wars', 'nike running shoes') to run Target's own site search, or a `category` path ('/c/cpus/-/N-01vhh', '/b/apple/-/N-5y3ej') to browse a Target category or brand page. Every product comes back with BOTH of Target's ids — the parent product id and the specific colour/size id — plus the name, brand, category, image, current price, the crossed-out list price when it is on sale, the star rating and rating count, and the product URL. Narrow with `sort`, `min_price` and `max_price`; page with `page` and `max_results`.","tags":["target"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string","example":"coffee maker","description":"What to search target.com for — a product type, a brand, or a brand plus a product ('laptop', 'coffee maker', 'lego star wars', 'nike running shoes'). This runs target.com's own site search and returns its own result order. Provide `query` OR `category`. Target serves 24 products per page and this API pages through them for you up to `max_results`; `meta.pagination` reports the deepest offset Target's own pagination links publish for that query, which is how many results it will let anyone page through (1 176 for 'laptop', 912 for 'lego', 432 for 'dog food' at the time of writing). IMPORTANT, so you can plan around it: target.com NEVER returns an empty search page — a keyword it cannot match comes back as 24 unrelated recommendations with a '200 results' label. This API measures that for you and reports it in `meta.keyword_match_rate` (real keywords score 0.62-1.00, nonsense scores 0.00), and warns in `meta.notes` when the rows are recommendations rather than matches."},"category":{"type":"string","example":"/c/cpus/-/N-01vhh","description":"A target.com category or brand page to browse instead of searching, given as the path of a target.com URL — `/c/cpus/-/N-01vhh`, `/c/marvel-collectibles/-/N-007on`, `/b/apple/-/N-5y3ej`. A full https://www.target.com/c/... URL is accepted too. Both forms come straight from Target's own sitemaps (6 215 category pages, 37 368 brand pages), which are the authoritative list: https://www.target.com/sitemap_taxonomy-categories-index.xml.gz and .../sitemap_taxonomy-brand-index.xml.gz. Note that some Target `/c/` URLs are landing/hub pages rather than product grids — those return zero products with `meta.notes` saying so and `related_categories` listing the real grids underneath them, rather than a misleading empty result."},"page":{"type":"integer","minimum":1,"maximum":200,"default":1,"example":1,"description":"Which page to start from (1-based). Target's page size is 24 and is not adjustable, so page 2 is results 25-48. Page until `meta.pagination.has_more` is false."},"max_results":{"type":"integer","minimum":1,"maximum":192,"default":24,"example":48,"description":"How many products to return (1-192). Target serves 24 per upstream page, so asking for more than 24 fetches more pages — each one is a further ~190 KB request against Target, so ask for what you will use."},"sort":{"type":"string","enum":["relevance","bestselling","PriceLow","PriceHigh","RatingHigh","newest"],"example":"PriceLow","description":"Result ordering, using Target's own sort tokens. Every value here is measured to change the order (`PriceLow` on 'laptop' returns $5.00-$13.49 first, `PriceHigh` returns $5 842-$3 999 first). `relevance` is Target's default, so passing it explicitly returns the same sequence as omitting `sort`. The list is closed on purpose: Target SILENTLY IGNORES a sort token it does not recognise and returns the default order, so an invalid value is rejected here rather than quietly given back to you as if it had sorted."},"min_price":{"type":"number","minimum":0,"example":100,"description":"Keep only products priced at or above this, in US dollars, using Target's own price filter. Verified to bite: `min_price=100&max_price=300` on 'laptop' returns only products between those bounds."},"max_price":{"type":"number","minimum":0,"example":300,"description":"Keep only products priced at or below this, in US dollars, using Target's own price filter. Combine with `min_price` for a band."}}},"example":{"query":"coffee maker","max_results":24}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}},"/target/v1/product_detail":{"post":{"operationId":"target_product_detail","summary":"Get one Target product in full, by Target's own id or by its target.com URL","description":"Get one Target product in full, by Target's own id or by its target.com URL. One call returns the UPC barcode, the shipping weight and package dimensions with Target's own units, the complete image gallery, the entire colour/size variant matrix with each variant's own price, list price, stock status, barcode, weight, dimensions, image and native Target id, the specification table parsed into name/value pairs, the brand, the category breadcrumb path, the current price and availability, the star rating with its full 1-5 distribution and Target's secondary ratings, the customer review photos, and the customer reviews inline.","tags":["target"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tcin":{"type":"string","example":"87328557","description":"Target's own product id (a 'TCIN'), exactly as `search` returns it — e.g. '87328557'. BOTH ids a search row gives you work: pass `product_tcin` (the parent product) or `variant_tcin` (one specific colour/size) and you get the same product back, because target.com resolves a variant id to its parent page. The response echoes what you asked for in `product.requested_tcin` and always reports the canonical parent in `product.tcin`. Provide `tcin`, or a product `url`."},"url":{"type":"string","example":"https://www.target.com/p/women-s-short-sleeve-t-shirt-wild-fable/-/A-87328557","description":"A full target.com product URL — an alternative to `tcin`. The slug is decorative: only the `A-<id>` part is read, so `/p/-/A-87328557` works too."},"reviews":{"type":"integer","minimum":0,"maximum":12,"default":8,"example":8,"description":"How many written customer reviews to inline with the product (0-12). This costs NO extra request — the reviews are already in the two pages this call fetches, so 0 saves you nothing but response size. The star rating, the rating count, the full 1-5 star distribution, the recommended percentage, Target's secondary ratings (comfort / quality / sizing / style, where the category has them) and the customer review photos always come back regardless of this value. Target itself only puts a limited number of review bodies on a product page, so `reviews.available_on_page` tells you how many there really were — asking for more than that is not an error, you simply get what exists."},"include_price":{"type":"boolean","default":true,"example":true,"description":"Whether to fetch the price, the availability and the per-variant price/stock matrix (default true). These live on a different target.com surface from the barcode, weight, dimensions, specs, images and reviews, so getting them costs ONE extra upstream request of roughly 0.7-1.0 MB. Set false when you only need the catalogue facts — it roughly halves the bytes and the latency of this call, and everything else is unchanged. `meta.route` and `meta.field_sources` always state which surfaces actually answered."}}},"example":{"tcin":"87328557","reviews":5}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":3}},"/target/v1/price":{"post":{"operationId":"target_price","summary":"Live price and stock for ONE Target product — the cheap way to refresh products you already hold, without paying for the whole product page","description":"Live price and stock for ONE Target product — the cheap way to refresh products you already hold, without paying for the whole product page. Pass the `tcin` search gave you (either `product_tcin` or `variant_tcin`) or a target.com product `url`. A specific colour/size id returns THAT variant's own price and stock; a parent id of a colour/size family returns every variant's price and stock in `variants[]` (Target prices the variants, not the family, so the top-level `price` is null there and `price_range` gives the min/max over the variants).","tags":["target"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"tcin":{"type":"string","example":"87328557","description":"Target's own product id (a 'TCIN'), exactly as `search` returns it — e.g. '87328557'. BOTH ids a search row gives you work: pass `product_tcin` (the parent product) or `variant_tcin` (one specific colour/size) and you get the same product back, because target.com resolves a variant id to its parent page. The response echoes what you asked for in `product.requested_tcin` and always reports the canonical parent in `product.tcin`. Provide `tcin`, or a product `url`."},"url":{"type":"string","example":"https://www.target.com/p/women-s-short-sleeve-t-shirt-wild-fable/-/A-87328557","description":"A full target.com product URL — an alternative to `tcin`. The slug is decorative: only the `A-<id>` part is read, so `/p/-/A-87328557` works too."}}},"example":{"tcin":"85963493"}}}},"responses":{"200":{"description":"Result envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Envelope"}}}},"401":{"description":"Missing or invalid x-api-key"},"429":{"description":"Rate limited or quota exhausted"}},"x-reefapi-credits":1}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"Envelope":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean"},"data":{"description":"Action result (shape varies per action)"},"meta":{"type":"object","description":"api, endpoint, mode, latency_ms, record_count, completeness_pct"},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}}}}}}}