[ § api ] · developer reference

The Itemic Index API.

REST over HTTPS, JSON in and out, RFC 7807 problem responses on errors. Free endpoints use the public-token header; paid endpoints use a per-organization API key issued from the Itemic dashboard.

Base URL

https://api.itemic.us/v1/index/

Format

JSON · UTF-8

SLA · paid

99.5% uptime

[ § auth ] · authentication

Two ways to call the Index.

Free tier

X-Itemic-Public-Token

A non-secret token, rate-limited per IP. Use for public reads of /lookup, /search, /brands. 100 requests/day with a free signup, 3/day without.

X-Itemic-Public-Token: public-anon

Paid tier

Authorization: ApiKey

API keys issued from app.itemic.us. One key per org, rotated on demand. Quota and entitlements follow the plan on file.

Authorization: ApiKey itm_live_abc123...

[ § endpoints ] · public reference

Public endpoints.

These endpoints are reachable from anywhere with the public token. Use them for personal lookups, evaluation, and lightweight integrations.

[ Free ]GET/lookup/{iid}

Look up a single IID

Returns the Index record for one IID.

cURL

curl https://api.itemic.us/v1/index/lookup/IID-PTGN-OUTW-3870E8 \
  -H "X-Itemic-Public-Token: <your-token>"

JavaScript

const res = await fetch(
  "https://api.itemic.us/v1/index/lookup/IID-PTGN-OUTW-3870E8",
  { headers: { "X-Itemic-Public-Token": process.env.ITEMIC_PUBLIC_TOKEN } },
);
const data = await res.json();

Python

import requests
r = requests.get(
    "https://api.itemic.us/v1/index/lookup/IID-PTGN-OUTW-3870E8",
    headers={"X-Itemic-Public-Token": os.environ["ITEMIC_PUBLIC_TOKEN"]},
)
data = r.json()

[ Free ]GET/search

Search by brand, product type, or category

Free-text search. Returns up to 50 hits per call.

Query parameters

q*Query string. Brand, product type, category, or IID prefix.
limitMax hits to return (1–50). Defaults to 20.

cURL

curl "https://api.itemic.us/v1/index/search?q=patagonia&limit=10" -H "X-Itemic-Public-Token: <token>"

JavaScript

const r = await fetch("https://api.itemic.us/v1/index/search?q=patagonia&limit=10", { headers: { "X-Itemic-Public-Token": token } });

Python

r = requests.get("https://api.itemic.us/v1/index/search", params={"q": "patagonia", "limit": 10}, headers={"X-Itemic-Public-Token": token})

[ Free ]GET/brands

Brand catalog

Returns the list of brands tracked in the Index.

cURL

curl "https://api.itemic.us/v1/index/brands?limit=100" -H "X-Itemic-Public-Token: <token>"

JavaScript

await fetch("https://api.itemic.us/v1/index/brands?limit=100", { headers: { "X-Itemic-Public-Token": token } });

Python

requests.get("https://api.itemic.us/v1/index/brands", params={"limit": 100}, headers={"X-Itemic-Public-Token": token})

[ § paid ] · authenticated surface

Paid endpoints.

Authenticated endpoints are available on Brand and Institutional plans. Full reference, parameters, and code samples appear in the dashboard once you have an API key.

[ Brand+ ]Cohort intelligenceAggregate stats across a brand and/or category.
[ Brand+ ]Pricing historyPer-day pricing observations for an IID.
[ Brand+ ]Sustainability metricsPer-unit and cumulative impact metrics.
[ Brand+ ]Category insightsAggregated views across categories and channels.
[ Brand+ ]Brand insightsBrand-level intelligence and rankings.
[ Institutional ]Sustainability rollupNetwork-wide sustainability aggregates for ESG reports.
[ Institutional ]Enterprise data accessBulk access for warehouse-side analytics and ML.

[ § errors ] · problem responses

Error format.

All non-2xx responses follow RFC 7807 application/problem+json:

{
  "type":   "https://itemic.us/errors/rate-limited",
  "title":  "Too Many Requests",
  "status": 429,
  "detail": "Daily free-tier limit of 100 lookups reached.",
  "retry_after": 86400
}

[ § go ] · get started

Pick a plan and grab a key in 30 seconds.

See pricing