{"openapi":"3.1.0","info":{"title":"ALETHEIA Safety Intelligence API","version":"1.3.0","description":"Chemical safety intelligence API with 1,879 compounds (3-tier classified), 959 materials (5-tier classified), and 1,262 consumer products (8-tier classified). Provides synthesized safety assessments across multiple exposure contexts (human adult, children, pets, aquatic life, etc.), regulatory classifications from 15+ agencies, exposure source mapping, and dose-response data.\n\n## Quickstart\n\n**1. Free lookup** — no key needed:\n```bash\ncurl \"https://api.aletheia.holisticquality.io/api/compound/hq-c-org-000001?context=human_adult\"\n```\n\n**2. Search by CAS number** — no key needed:\n```bash\ncurl \"https://api.aletheia.holisticquality.io/api/compound/cas/1071-83-6\"\n```\n\n**3. Batch lookup** — no key needed (up to 20 per request):\n```bash\ncurl \"https://api.aletheia.holisticquality.io/api/compounds/batch?ids=hq-c-org-000001,hq-c-org-000033&context=dog\"\n```\n\n**4. Search & filter** — requires API key:\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/compounds?search=phthalate&risk=high\"\n```\n\n**5. Regulatory deep-dive** — requires API key:\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/regulatory/hq-c-org-000001\"\n```\n\n**6. Exposure sources** — requires API key:\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/found-in/hq-c-org-000001\"\n```\n\n## SDKs\n\nInstall the official SDK for typed responses, automatic retries, and webhook verification:\n\n```bash\npip install aletheia-safety    # Python\nnpm install aletheia-safety    # Node.js\n```\n\n**Python:**\n```python\nfrom aletheia_safety import Aletheia\nclient = Aletheia(api_key=\"YOUR_KEY\")\ncompound = client.compound(\"hq-c-org-000001\")\nprint(compound[\"synthesis\"][\"overall_risk\"])\n```\n\n**Node.js:**\n```js\nimport { Aletheia } from 'aletheia-safety';\nconst client = new Aletheia({ apiKey: 'YOUR_KEY' });\nconst compound = await client.compound('hq-c-org-000001');\n```\n\n**Verify webhook signatures:**\n```python\nAletheia.verify_webhook_signature(body, request.headers[\"X-Aletheia-Signature\"], secret)\n```\n\n## Authentication\n\nMost single-item endpoints are **free and open** — no API key required.\n\nList, regulatory, and exposure endpoints require a paid API key passed via the `X-API-Key` header or `api_key` query parameter.\n\n| Tier | Requests/Day | Price |\n|------|-------------|-------|\n| Public | 500/IP | Free |\n| Developer | 10,000 | $29/mo |\n| Pro | 100,000 | $99/mo |\n| Enterprise | Unlimited | Contact us |\n\nGet a key at [aletheia.holisticquality.io/pricing](https://aletheia.holisticquality.io/pricing).\n\n**Free trial:** `POST /api/keys/trial` with `{\"email\": \"you@example.com\"}` — 7 days of Developer tier, no credit card required.\n\n## Rate Limit Headers\n\nAll responses include:\n- `X-RateLimit-Remaining` — requests left today\n- `X-API-Tier` — your current tier\n\n## Caching\n\nResponses are cached at the edge (Vercel CDN). Single compound lookups cache for 1 hour; list endpoints for 5 minutes; reference data for 2 hours.","termsOfService":"https://aletheia.holisticquality.io/terms","contact":{"name":"Holistic Quality LLC","url":"https://aletheia.holisticquality.io","email":"api@holisticquality.io"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.aletheia.holisticquality.io","description":"Production"}],"security":[],"tags":[{"name":"Compounds","description":"Chemical compound safety data with multi-context synthesis"},{"name":"Materials","description":"Material composition, behavior, and safety data"},{"name":"Products","description":"Consumer product safety and composition data"},{"name":"Regulatory","description":"Regulatory classifications by agency (IARC, EPA, EU CLP, etc.)"},{"name":"Exposure","description":"Where compounds are found — product categories and exposure sources"},{"name":"Relationships","description":"Entity relationship graph — compound ↔ material ↔ product connections with multi-hop traversal"},{"name":"Reference","description":"Safety contexts, API metadata, and health checks"},{"name":"Keys","description":"API key management — status, recovery, rotation, and usage history"},{"name":"Badges","description":"Embeddable SVG safety badges for websites and e-commerce"},{"name":"Webhooks","description":"Push notifications for compound data changes"},{"name":"Watchlist","description":"Personal compound monitoring — track compounds and get enriched status updates"},{"name":"Changelog","description":"Regulatory and data change feed — poll for updates to tracked compounds"},{"name":"Export","description":"Bulk download — export full entity sets as CSV or JSON for offline analysis and data pipelines"}],"paths":{"/api":{"get":{"tags":["Reference"],"summary":"API root — service info and endpoint directory","operationId":"getRoot","responses":{"200":{"description":"Service info with endpoint directory and example URLs","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RootResponse"}}}}}}},"/api/health":{"get":{"tags":["Reference"],"summary":"Health check","operationId":"getHealth","responses":{"200":{"description":"Service health status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"status":"healthy","version":"1.0.0","timestamp":"2026-03-13T12:00:00.000Z","platform":"Vercel Serverless"}}}}}}},"/api/compound/{id}/alternatives":{"get":{"tags":["Compounds"],"summary":"Get safer alternatives for a compound","description":"Returns safer alternatives with effectiveness ratings. Free tier: basic list (name + effectiveness). Developer+: full data with tradeoffs, cost, regulatory status, and linked compound IDs.","operationId":"getCompoundAlternatives","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Compound ID (e.g., hq-c-org-000001)"}],"responses":{"200":{"description":"Alternatives list","content":{"application/json":{"schema":{"type":"object","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"alternatives":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"effectiveness":{"type":"string","nullable":true},"tradeoffs":{"type":"string","nullable":true,"description":"Developer+ only"},"relative_cost":{"type":"string","nullable":true,"description":"Developer+ only"},"regulatory_status":{"type":"string","nullable":true,"description":"Developer+ only"},"compound_id":{"type":"string","nullable":true,"description":"Developer+ only — linked compound ID if available"}}}},"count":{"type":"integer"},"no_substitute_reason":{"type":"string","nullable":true},"mitigation_strategies":{"description":"Developer+ only"},"_tier":{"type":"string","enum":["basic","full"]}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"description":"Compound not found"}}}},"/api/compound/{id}":{"get":{"tags":["Compounds"],"summary":"Get synthesized safety assessment for a compound","description":"Returns a safety synthesis for the given compound and context. The synthesis engine vectorizes regulatory classifications, computes hazard metrics across 8 dimensions, and returns a risk level with supporting evidence.\n\n**No API key required** — this is a free endpoint.\n\nIf synthesis is unavailable (compound lacks vectorizable regulatory data), returns raw safety data with `schema: \"legacy\"`.","operationId":"getCompound","parameters":[{"$ref":"#/components/parameters/CompoundId"},{"name":"context","in":"query","description":"Safety context for synthesis (e.g., `human_adult`, `dog`, `cat`, `human_child`). Defaults to the compound's primary context.","schema":{"type":"string","pattern":"^[a-z][a-z0-9_]{1,39}$","example":"human_adult"}},{"name":"all_contexts","in":"query","description":"Set to `true` to get synthesis results for all available contexts at once.","schema":{"type":"string","enum":["true"]}}],"responses":{"200":{"description":"Synthesized safety assessment (or all-context results)","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/CompoundSynthesis"},{"$ref":"#/components/schemas/CompoundAllContexts"},{"$ref":"#/components/schemas/CompoundLegacy"}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"422":{"description":"Compound uses unsupported schema or synthesis is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Schema not supported","hq_id":"hq-c-org-000999","name":"Example Compound","message":"This compound uses the v2 research schema which does not expose queryable safety contexts.","schema":"v2_research"}}}},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl \"https://api.aletheia.holisticquality.io/api/compound/hq-c-org-000001?context=human_adult\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/compound/hq-c-org-000001\",\n    params={\"context\": \"human_adult\"}\n)\ndata = resp.json()\nprint(f\"{data['name']}: {data['risk_level']} risk\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/compound/hq-c-org-000001?context=human_adult\"\n);\nconst data = await resp.json();\nconsole.log(`${data.name}: ${data.risk_level} risk`);"}]}},"/api/compound/{id}/raw":{"get":{"tags":["Compounds"],"summary":"Get raw compound JSON (no synthesis)","description":"Returns the full compound data file as stored, without running the synthesis engine. Useful for accessing all fields including crossrefs, identity, dose_response, etc.","operationId":"getCompoundRaw","parameters":[{"$ref":"#/components/parameters/CompoundId"}],"responses":{"200":{"description":"Full raw compound JSON","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompoundRaw"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/compound/cas/{cas}":{"get":{"tags":["Compounds"],"summary":"Look up a compound by CAS number","description":"Reverse CAS lookup. Returns compound metadata inline, or optionally redirects to the canonical compound endpoint.","operationId":"getCompoundByCas","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"cas","in":"path","required":true,"description":"CAS Registry Number (e.g., `1071-83-6` for Glyphosate)","schema":{"type":"string","pattern":"^\\d{1,7}-\\d{2}-\\d$","example":"1071-83-6"}},{"name":"redirect","in":"query","description":"If `true`, returns a 302 redirect to `/api/compound/{id}` instead of inline data.","schema":{"type":"string","enum":["true","false"],"default":"false"}},{"name":"context","in":"query","description":"Context passed through on redirect.","schema":{"type":"string"}}],"responses":{"200":{"description":"Compound metadata for the given CAS number","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CasLookupResponse"}}}},"302":{"description":"Redirect to canonical compound endpoint (when `redirect=true`)"},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/compound/cas/1071-83-6\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/compound/cas/1071-83-6\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"}\n)\ndata = resp.json()\nprint(f\"Found: {data['name']} ({data['hq_id']})\")"}]}},"/api/compounds":{"get":{"tags":["Compounds"],"summary":"List and search compounds","description":"**Requires Developer+ API key.** Returns a paginated list of compounds with optional search and filters.","operationId":"listCompounds","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"},{"name":"search","in":"query","description":"Free-text search across compound name, CAS, and synonyms.","schema":{"type":"string","example":"glyphosate"}},{"name":"risk","in":"query","description":"Filter by risk level in the given context.","schema":{"type":"string","enum":["low","moderate","high","very_high","critical"]}},{"name":"context","in":"query","description":"Context for risk level filtering. Only used when `risk` is specified.","schema":{"type":"string","default":"human_adult"}},{"name":"hazard","in":"query","description":"Filter by hazard profile (e.g., `herbicide`, `plasticizer`, `flame_retardant`).","schema":{"type":"string"}},{"name":"cas","in":"query","description":"Filter by exact CAS number.","schema":{"type":"string"}},{"name":"type_filter","in":"query","description":"Filter by compound functional type (e.g., `surfactant`, `preservative`, `plasticizer`, `uv_filter`, `fragrance_ingredient`).","schema":{"type":"string"}},{"name":"category_filter","in":"query","description":"Filter by compound category (e.g., `food_additive`, `pesticide`, `dietary_supplement`).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of compounds","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompoundListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/compounds?search=phthalate&risk=high&limit=10\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/compounds\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"},\n    params={\"search\": \"phthalate\", \"risk\": \"high\", \"limit\": 10}\n)\ndata = resp.json()\nfor compound in data[\"compounds\"]:\n    print(f\"{compound['hq_id']}: {compound['name']} — {compound['risk_levels'].get('human_adult')}\")\nprint(f\"Page {data['pagination']['page']} of {data['pagination']['total_pages']}\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/compounds?search=phthalate&risk=high&limit=10\",\n  { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst data = await resp.json();\ndata.compounds.forEach(c => console.log(`${c.hq_id}: ${c.name}`));"}]}},"/api/compounds/batch":{"get":{"tags":["Compounds"],"summary":"Batch lookup — up to 20 compounds in one request","operationId":"batchCompounds","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"ids","in":"query","required":true,"description":"Comma-separated compound IDs (max 20).","schema":{"type":"string","example":"hq-c-org-000001,hq-c-org-000033,hq-c-org-000100"}},{"name":"context","in":"query","description":"Extract `risk_level` for this context on each compound.","schema":{"type":"string","example":"human_adult"}}],"responses":{"200":{"description":"Batch results keyed by compound ID","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl \"https://api.aletheia.holisticquality.io/api/compounds/batch?ids=hq-c-org-000001,hq-c-org-000033,hq-c-org-000100&context=dog\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/compounds/batch\",\n    params={\"ids\": \"hq-c-org-000001,hq-c-org-000033,hq-c-org-000100\", \"context\": \"dog\"}\n)\ndata = resp.json()\nfor cid, info in data[\"results\"].items():\n    if \"error\" not in info:\n        print(f\"{cid}: {info['name']} — {info.get('risk_level', 'N/A')}\")\n    else:\n        print(f\"{cid}: {info['error']}\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/compounds/batch?ids=hq-c-org-000001,hq-c-org-000033,hq-c-org-000100&context=dog\"\n);\nconst { results, meta } = await resp.json();\nconsole.log(`Found ${meta.found} of ${meta.requested}`);\nObject.entries(results).forEach(([id, info]) => {\n  console.log(`${id}: ${info.name ?? info.error}`);\n});"}]}},"/api/compounds/compare":{"get":{"tags":["Compounds"],"summary":"Compare 2-5 compounds side-by-side (single or multi-context)","description":"**Requires Developer+ API key.** Returns a rich side-by-side comparison of 2-5 compounds including risk profile differentials, regulatory agency agreement/disagreement matrices, LD50 toxicity ratios, environmental fate deltas, shared exposure sources, and an auto-generated summary of key differences.\n\n**Multi-context mode:** Pass `contexts` (plural, comma-separated, 2-5 contexts) instead of `context` to compare compounds across multiple exposure contexts simultaneously. Returns a compound × context risk matrix with escalation factors, vulnerability rankings, and cross-context insights. Example: `?ids=X,Y&contexts=human_adult,human_child,dog`","operationId":"compareCompounds","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"ids","in":"query","required":true,"description":"Comma-separated compound IDs (min 2, max 5). Duplicates are automatically removed.","schema":{"type":"string","example":"hq-c-org-000001,hq-c-org-000033"}},{"name":"context","in":"query","description":"Safety context for risk profile comparison (single-context mode). Default: `human_adult`. Mutually exclusive with `contexts`.","schema":{"type":"string","default":"human_adult","example":"human_adult"}},{"name":"contexts","in":"query","description":"Comma-separated contexts for multi-context comparison (2-5 contexts). Returns a compound × context risk matrix with escalation factors and vulnerability rankings. Mutually exclusive with `context`.","schema":{"type":"string","example":"human_adult,human_child,dog"}}],"responses":{"200":{"description":"Side-by-side comparison with computed differentials","content":{"application/json":{"schema":{"type":"object","properties":{"comparison":{"type":"object","properties":{"compounds":{"type":"array","description":"Compound identifiers (hq_id, name, cas)"},"context":{"type":"string"},"risk_profiles":{"type":"object","description":"Synthesized risk levels + magnitude deltas"},"regulatory":{"type":"object","description":"Agency classification matrix + agreement/disagreement analysis"},"dose_response":{"type":"object","description":"LD50 ratios, NOAEL comparison, RfD values"},"hazard_profiles":{"type":"object","description":"Hazard, carcinogenicity, GHS comparison"},"environmental_fate":{"type":"object","description":"Bioaccumulation, persistence, soil mobility"},"exposure_sources":{"type":"object","description":"Shared vs unique found-in categories"},"summary":{"type":"object","description":"Top key_differences + shared_traits"}}},"meta":{"type":"object"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Premium feature — public tier not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"One or more compounds not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/compounds/compare?ids=hq-c-org-000001,hq-c-org-000033&context=human_adult\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/compounds/compare\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"},\n    params={\"ids\": \"hq-c-org-000001,hq-c-org-000033\", \"context\": \"human_adult\"}\n)\ndata = resp.json()\nfor diff in data[\"comparison\"][\"summary\"][\"key_differences\"]:\n    print(f\"• {diff}\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/compounds/compare?ids=hq-c-org-000001,hq-c-org-000033&context=human_adult\",\n  { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst { comparison } = await resp.json();\nconsole.log(\"Key differences:\", comparison.summary.key_differences);\nconsole.log(\"Shared traits:\", comparison.summary.shared_traits);"}]}},"/api/materials":{"get":{"tags":["Materials"],"summary":"List and search materials","description":"**Requires Developer+ API key.** Returns a paginated list of materials (polymers, composites, alloys, etc.).","operationId":"listMaterials","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"},{"name":"search","in":"query","description":"Free-text search across material name.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of materials","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/material/{id}":{"get":{"tags":["Materials"],"summary":"Get a single material","description":"Returns the full material data including composition (base compounds + additives + contaminants), behavior (leaching, degradation, offgassing, thermal), safety summary, and alternatives.","operationId":"getMaterial","parameters":[{"name":"id","in":"path","required":true,"description":"Material ID","schema":{"type":"string","pattern":"^hq-m-[a-z]{3}-\\d{6}$","example":"hq-m-str-000001"}}],"responses":{"200":{"description":"Full material data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialRaw"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/products":{"get":{"tags":["Products"],"summary":"List and search products","description":"**Requires Developer+ API key.** Returns a paginated list of consumer products.","operationId":"listProducts","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"$ref":"#/components/parameters/Page"},{"$ref":"#/components/parameters/Limit"},{"name":"search","in":"query","description":"Free-text search across product name, category, tags, and common names.","schema":{"type":"string"}},{"name":"risk","in":"query","description":"Filter by overall risk level.","schema":{"type":"string","enum":["extreme","severe","high","moderate_to_high","moderate","low","negligible"]}},{"name":"tier","in":"query","description":"Filter by product tier (CHD, BDY, FOD, HOM, OUT, PET, WER, SPE).","schema":{"type":"string","enum":["CHD","BDY","FOD","HOM","OUT","PET","WER","SPE"]}},{"name":"category_filter","in":"query","description":"Filter by primary category (children, personal_care, food_contact, etc.).","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of products","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductListResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/product/{id}":{"get":{"tags":["Products"],"summary":"Get product safety profile with synthesis data","description":"Returns the full product safety profile including pre-computed risk synthesis, compound composition, hazard summary, exposure assessment, regulatory status, consumer guidance, and lifecycle data. The `synthesis` block contains algorithmically derived risk levels from the product's compound composition. Free tier: full profile except `compound_traces`. Developer+ tier: includes `compound_traces` showing per-compound risk contributions.","operationId":"getProduct","parameters":[{"name":"id","in":"path","required":true,"description":"Product ID (format: hq-p-{tier}-{number})","schema":{"type":"string","pattern":"^hq-p-[a-z]{3}-\\d{6}$","example":"hq-p-chd-000001"}}],"responses":{"200":{"description":"Full product safety profile with synthesis","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductProfile"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/product/{id}/raw":{"get":{"tags":["Products"],"summary":"Get raw product JSON","description":"Returns the unprocessed product JSON file as stored in the database. No response shaping or auth tier gating applied.","operationId":"getProductRaw","parameters":[{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string","pattern":"^hq-p-[a-z]{3}-\\d{6}$","example":"hq-p-fod-000001"}}],"responses":{"200":{"description":"Raw product data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductRaw"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"404":{"$ref":"#/components/responses/NotFound"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/contexts":{"get":{"tags":["Reference"],"summary":"List all safety contexts","description":"Returns all valid safety contexts grouped by category (human, animal, exposure route, environmental), with descriptions and aliases.","operationId":"listContexts","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"responses":{"200":{"description":"All safety contexts with grouping","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContextsResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/regulatory/{id}":{"get":{"tags":["Regulatory"],"summary":"Get regulatory classifications for a compound","description":"**Requires Developer+ API key.** Returns all regulatory classifications with agency breakdown and summary statistics.","operationId":"getRegulatory","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"$ref":"#/components/parameters/CompoundId"}],"responses":{"200":{"description":"Regulatory classifications with summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegulatoryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/regulatory/hq-c-org-000001\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/regulatory/hq-c-org-000001\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"}\n)\ndata = resp.json()\nprint(f\"{data['name']}: {data['regulatory']['count']} classifications\")\nfor agency, count in data[\"regulatory\"][\"summary\"][\"by_agency\"].items():\n    print(f\"  {agency}: {count}\")"}]}},"/api/regulatory/agencies":{"get":{"tags":["Regulatory"],"summary":"List all regulatory agencies with classification counts","description":"**Requires Developer+ API key.** Returns a summary of all regulatory agencies in the database, sorted by number of classifications.","operationId":"listAgencies","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"responses":{"200":{"description":"Agency summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgenciesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}}}},"/api/regulatory/by-agency/{agency}":{"get":{"tags":["Regulatory"],"summary":"List compounds classified by a specific agency","description":"**Requires Developer+ API key.** Returns compounds that have been classified by the given regulatory agency (e.g., IARC, EPA, EU CLP).","operationId":"getByAgency","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"agency","in":"path","required":true,"description":"Agency name (case-insensitive)","schema":{"type":"string","example":"IARC"}},{"name":"limit","in":"query","description":"Maximum results to return.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}}],"responses":{"200":{"description":"Compounds classified by this agency","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ByAgencyResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/regulatory/by-agency/IARC?limit=10\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/regulatory/by-agency/IARC\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"},\n    params={\"limit\": 10}\n)\ndata = resp.json()\nprint(f\"{data['agency']}: {data['total_matches']} compounds classified\")\nfor r in data[\"results\"]:\n    print(f\"  {r['hq_id']}: {r['name']}\")"}]}},"/api/found-in/{id}":{"get":{"tags":["Exposure"],"summary":"Get exposure sources for a compound","description":"**Requires Developer+ API key.** Returns where a compound is found — product categories, specific examples, and exposure notes.","operationId":"getFoundIn","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"$ref":"#/components/parameters/CompoundId"}],"responses":{"200":{"description":"Exposure sources with category summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FoundInResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/found-in/hq-c-org-000001\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/found-in/hq-c-org-000001\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"}\n)\ndata = resp.json()\nprint(f\"{data['name']} found in {data['summary']['total_categories']} categories:\")\nfor cat in data[\"found_in\"]:\n    print(f\"  {cat['category']}: {len(cat.get('examples', []))} sources\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/found-in/hq-c-org-000001\",\n  { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst data = await resp.json();\ndata.found_in.forEach(cat =>\n  console.log(`${cat.category}: ${cat.examples?.length ?? 0} sources`)\n);"}]}},"/api/found-in/categories":{"get":{"tags":["Exposure"],"summary":"List all exposure categories with compound counts","description":"**Requires Developer+ API key.** Returns a summary of all product/exposure categories (Food, Building, Personal Care, etc.).","operationId":"listCategories","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"responses":{"200":{"description":"Category summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoriesResponse"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/found-in/categories\""}]}},"/api/found-in/by-category/{category}":{"get":{"tags":["Exposure"],"summary":"List compounds found in a specific category","description":"**Requires Developer+ API key.** Returns compounds found in the given product/exposure category (e.g., Food, Personal Care, Building).","operationId":"getByCategory","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"category","in":"path","required":true,"description":"Product/exposure category (case-insensitive)","schema":{"type":"string","example":"Food"}},{"name":"limit","in":"query","description":"Maximum results to return.","schema":{"type":"integer","minimum":1,"maximum":1000,"default":100}}],"responses":{"200":{"description":"Compounds found in this category","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ByCategoryResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/found-in/by-category/Food?limit=10\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/found-in/by-category/Food\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"},\n    params={\"limit\": 10}\n)\ndata = resp.json()\nprint(f\"Category '{data['category']}': {data['total_matches']} compounds\")\nfor r in data[\"results\"]:\n    print(f\"  {r['hq_id']}: {r['name']}\")"}]}},"/api/keys/status":{"get":{"tags":["Keys"],"summary":"Check API key status and usage","operationId":"getKeyStatus","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"responses":{"200":{"description":"Key status with usage info","content":{"application/json":{"schema":{"$ref":"#/components/schemas/KeyStatusResponse"},"example":{"tier":"developer","active":true,"created":"2026-03-01T00:00:00.000Z","trial":false,"usage":{"today":1234,"limit":10000,"remaining":8766,"resets":"2026-03-14T00:00:00Z (next day)"}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"503":{"description":"OAS-009: Redis unavailable — key status cannot be checked. Retry with backoff."}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/keys/status\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/keys/status\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"}\n)\nusage = resp.json()[\"usage\"]\nprint(f\"Used {usage['today']}/{usage['limit']} — {usage['remaining']} remaining\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/keys/status\",\n  { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst { tier, usage } = await resp.json();\nconsole.log(`${tier}: ${usage.remaining} requests remaining today`);"}]}},"/api/keys/recover":{"post":{"tags":["Keys"],"summary":"Recover API key(s) via email","description":"Sends all active API keys to the given email address. Always returns 200 regardless of whether the email exists (prevents enumeration). Rate limited to 3 attempts per email per hour.","operationId":"recoverKeys","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","example":"user@example.com"}}}}}},"responses":{"200":{"description":"Recovery email sent (if account exists)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"If an account exists for that email, your API key(s) have been sent."}}}}}},"400":{"description":"Invalid JSON or email format","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/keys/rotate":{"post":{"tags":["Keys"],"summary":"Rotate API key — replace a compromised key","description":"Generates a new API key, migrates all associated data (watchlist, webhooks), and deactivates the old key. Trial keys cannot be rotated. Limited to one rotation per key per hour. A notification email is sent to the key owner.","operationId":"rotateKey","security":[{"ApiKeyHeader":[]}],"responses":{"200":{"description":"Key rotated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"Key rotated successfully. Save your new key — it will not be shown again."},"key":{"type":"string","example":"aletheia_live_a1b2c3d4e5f6..."},"tier":{"type":"string","example":"developer"},"old_key_deactivated":{"type":"boolean","example":true},"watchlist_migrated":{"type":"boolean","example":true},"webhooks_migrated":{"type":"integer","example":2}}}}}},"401":{"description":"No API key provided or key invalid/inactive","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Trial keys cannot be rotated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"405":{"description":"Method not allowed (POST only)"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"description":"Key storage unavailable"}}}},"/api/relationships/{id}":{"get":{"tags":["Relationships"],"summary":"Get direct relationships for an entity","description":"**Requires Developer+ API key.** Returns all compounds, materials, and products directly connected to the given entity. Supports filtering by related entity type.","operationId":"getRelationships","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Entity ID (compound, material, or product)","schema":{"type":"string","pattern":"^hq-[cmp](-[a-z]{3})?-\\d{4,6}$"},"examples":{"compound":{"value":"hq-c-org-000007","summary":"DEHP (phthalate plasticizer)"},"material":{"value":"hq-m-str-000001","summary":"PVC plastic"},"product":{"value":"hq-p-bdy-000001","summary":"Conventional Hair Shampoo"}}},{"name":"rel_type","in":"query","required":false,"description":"Filter relationships by entity type","schema":{"type":"string","enum":["compound","material","product"]}}],"responses":{"200":{"description":"Entity relationships","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["compound","material","product"]},"relationships":{"type":"object","properties":{"compounds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"pct":{"type":"string"}}}},"materials":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"}}}},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"}}}}}},"total_edges":{"type":"integer"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/relationships/hq-c-org-000007\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/relationships/hq-c-org-000007\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"}\n)\ndata = resp.json()\nprint(f\"{data['name']} connected to:\")\nfor rel_type in ['compounds', 'materials', 'products']:\n    items = data['relationships'].get(rel_type, [])\n    if items:\n        print(f\"  {len(items)} {rel_type}:\")\n        for item in items[:3]:\n            print(f\"    {item['id']}: {item['name']} ({item.get('role', '')})\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/relationships/hq-c-org-000007\",\n  { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst data = await resp.json();\nconsole.log(`${data.name}: ${data.total_edges} connections`);\ndata.relationships.products?.forEach(p =>\n  console.log(`  Found in: ${p.name} (${p.role})`)\n);"}]}},"/api/relationships/{id}/graph":{"get":{"tags":["Relationships"],"summary":"Multi-hop graph traversal from an entity","description":"**Requires Developer+ API key.** BFS traversal from an entity through the relationship graph. Returns nodes and edges up to the specified depth (1-3). Useful for exploring \"what products contain compounds found in this material?\"","operationId":"getRelationshipGraph","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Starting entity ID","schema":{"type":"string","pattern":"^hq-[cmp](-[a-z]{3})?-\\d{4,6}$"}},{"name":"depth","in":"query","required":false,"description":"Traversal depth (1-3, default 1)","schema":{"type":"integer","minimum":1,"maximum":3,"default":2}},{"name":"rel_type","in":"query","required":false,"description":"Only traverse edges to this entity type","schema":{"type":"string","enum":["compound","material","product"]}}],"responses":{"200":{"description":"Graph traversal result with nodes and edges","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"depth":{"type":"integer"},"graph":{"type":"object","properties":{"nodes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"type":{"type":"string"},"depth":{"type":"integer"}}}},"edges":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"type":{"type":"string"},"role":{"type":"string"},"depth":{"type":"integer"}}}},"node_count":{"type":"integer"},"edge_count":{"type":"integer"}}}}}}}}},"x-code-samples":[{"lang":"cURL","label":"cURL — 2-hop traversal from PVC","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/relationships/hq-m-str-000001/graph?depth=2\""}]}},"/api/relationships/stats":{"get":{"tags":["Relationships"],"summary":"Relationship graph statistics","description":"**Requires Developer+ API key.** Returns overall graph statistics: node count, edge count, and connected entity counts by type.","operationId":"getRelationshipStats","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"responses":{"200":{"description":"Graph statistics","content":{"application/json":{"schema":{"type":"object","properties":{"generated":{"type":"string","format":"date-time"},"stats":{"type":"object","properties":{"nodes":{"type":"integer"},"edges":{"type":"integer"},"compounds_with_links":{"type":"integer"},"materials_with_links":{"type":"integer"},"products_with_links":{"type":"integer"}}}}}}}}}}},"/api/badge/{id}":{"get":{"tags":["Badges"],"summary":"Get embeddable SVG safety badge for a compound","description":"Returns an SVG image badge showing the compound's risk level, similar to shields.io. Embed via `<img>` tag — no iframe, no API key, CDN-cacheable (24h).\n\n**Embed example:**\n```html\n<a href=\"https://aletheia.holisticquality.io\">\n  <img src=\"https://api.aletheia.holisticquality.io/api/badge/hq-c-org-000001?context=human_adult\"\n       alt=\"ALETHEIA Safety Badge\" />\n</a>\n```","operationId":"getBadge","parameters":[{"$ref":"#/components/parameters/CompoundId"},{"name":"context","in":"query","description":"Safety context for risk level. Defaults to `human_adult`.","schema":{"type":"string","default":"human_adult"}},{"name":"style","in":"query","description":"Badge visual style.","schema":{"type":"string","enum":["flat","flat-square","pill"],"default":"flat"}},{"name":"label","in":"query","description":"Left-side label text.","schema":{"type":"string","default":"ALETHEIA"}}],"responses":{"200":{"description":"SVG badge image","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"400":{"description":"Invalid ID or context"},"404":{"description":"Compound not found (returns gray \"not found\" badge)"}},"x-code-samples":[{"lang":"HTML","label":"HTML embed","source":"<img src=\"https://api.aletheia.holisticquality.io/api/badge/hq-c-org-000001?context=human_adult\" alt=\"Safety Badge\" />"},{"lang":"Markdown","label":"Markdown","source":"![Safety Badge](https://api.aletheia.holisticquality.io/api/badge/hq-c-org-000001?context=human_adult)"}]}},"/api/search":{"get":{"tags":["Compounds","Materials","Products"],"summary":"Unified full-text search across all entity types","description":"Searches compounds, products, and materials simultaneously. Returns relevance-scored results with entity_type field. Results are sorted by relevance score (highest first).","operationId":"search","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"q","in":"query","required":true,"description":"Search query string. Searches across entity names, identifiers, types, categories, and synonyms. Minimum 2 characters.","schema":{"type":"string","minLength":2,"example":"glyphosate"}},{"name":"limit","in":"query","description":"Maximum number of results to return per page.","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","description":"Number of results to skip for pagination.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"type","in":"query","description":"Filter results by entity type. If omitted, returns all matching types.","schema":{"type":"string","enum":["compound","product","material"],"example":"compound"}}],"responses":{"200":{"description":"Search results with relevance scores","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/search?q=phthalate&limit=10\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/search\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"},\n    params={\"q\": \"phthalate\", \"limit\": 10}\n)\ndata = resp.json()\nfor result in data[\"results\"]:\n    print(f\"{result['entity_type']}: {result['name']} (score: {result['score']})\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/search?q=phthalate&limit=10\",\n  { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst data = await resp.json();\ndata.results.forEach(r => console.log(`${r.entity_type}: ${r.name}`));"}]}},"/api/filter":{"get":{"tags":["Compounds"],"summary":"Advanced filtering for compounds","description":"Filter compounds using AND logic across multiple dimensions. At least one filter parameter must be specified. Results are sorted alphabetically by compound name.","operationId":"filter","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"risk","in":"query","description":"Filter by risk level in the specified context.","schema":{"type":"string","enum":["very_low","low","low_moderate","moderate","high","very_high"]}},{"name":"context","in":"query","description":"Safety context for risk filtering. Only used when `risk` is specified. Defaults to `human_adult`.","schema":{"type":"string","default":"human_adult","example":"human_adult"}},{"name":"type","in":"query","description":"Filter by compound functional type (e.g., `preservative`, `herbicide`, `plasticizer`, `surfactant`).","schema":{"type":"string","example":"preservative"}},{"name":"category","in":"query","description":"Filter by compound category (e.g., `food_additive`, `pesticide`, `cosmetic_ingredient`).","schema":{"type":"string"}},{"name":"hazard","in":"query","description":"Filter by hazard profile classification.","schema":{"type":"string"}},{"name":"hazard_keyword","in":"query","description":"Search for keywords within the hazard profile (e.g., `carcinogen`, `neurotoxic`).","schema":{"type":"string"}},{"name":"agency","in":"query","description":"Filter by regulatory agency that has classified the compound (e.g., `EPA`, `IARC`, `EU`).","schema":{"type":"string","example":"EPA"}},{"name":"cas","in":"query","description":"Filter by exact CAS number (e.g., `7732-18-5`).","schema":{"type":"string"}},{"name":"cas_prefix","in":"query","description":"Filter by CAS number prefix for matching a range (e.g., `1071` matches all CAS numbers starting with 1071-).","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of results to return per page.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","description":"Number of results to skip for pagination.","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Filtered compound results with applied filters metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FilterResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"405":{"$ref":"#/components/responses/MethodNotAllowed"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/filter?risk=high&context=human_adult&type=herbicide\""},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/filter\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"},\n    params={\"risk\": \"high\", \"context\": \"human_adult\", \"type\": \"herbicide\"}\n)\ndata = resp.json()\nprint(f\"Found {data['total']} compounds matching filters\")\nfor compound in data[\"results\"]:\n    print(f\"  {compound['name']} (CAS: {compound['cas']})\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/filter?risk=high&context=human_adult&type=herbicide\",\n  { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst data = await resp.json();\nconsole.log(`Found ${data.total} compounds`);\ndata.results.forEach(c => console.log(`  ${c.name}`));"}]}},"/api/export":{"get":{"tags":["Export"],"summary":"Bulk export entity set as CSV or JSON","description":"**Requires Developer API key or above.** Downloads all compounds, materials, or products matching the given filters as a CSV or JSON file attachment. Counts as 10 requests against your daily quota. Useful for offline analysis, seeding local databases, or building data pipelines.\n\n**Supported types:** `compounds`, `materials`, `products`\n\n**Supported formats:** `csv` (default), `json`\n\nApplies the same filters as the list endpoints (`/api/compounds`, `/api/materials`, `/api/products`).","operationId":"exportEntities","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"type","in":"query","required":true,"schema":{"type":"string","enum":["compounds","materials","products"]},"description":"Entity type to export."},{"name":"format","in":"query","required":false,"schema":{"type":"string","enum":["csv","json"],"default":"csv"},"description":"Output format. `csv` returns a flat spreadsheet; `json` returns a structured JSON download."},{"name":"detail","in":"query","required":false,"schema":{"type":"string","enum":["full"]},"description":"OAS-007: Set to `full` for expanded columns (Pro+ only, compounds). Includes cross-refs, properties, all contexts."},{"name":"search","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by name/keyword (compounds, materials, products)."},{"name":"risk","in":"query","required":false,"schema":{"type":"string","enum":["low","moderate","moderate_to_high","high","severe"]},"description":"Filter by risk level in the given context (compounds only)."},{"name":"context","in":"query","required":false,"schema":{"type":"string","enum":["human_adult","human_child","human_pregnant","human_elderly","dog","cat"],"default":"human_adult"},"description":"Exposure context for risk filter (compounds only)."},{"name":"hazard","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by hazard profile (compounds only, e.g. `endocrine_disruptor`)."},{"name":"type_filter","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by compound type (compounds only, e.g. `herbicide`, `fragrance`)."},{"name":"category_filter","in":"query","required":false,"schema":{"type":"string"},"description":"Filter by compound category (compounds only)."}],"responses":{"200":{"description":"File download — CSV or JSON attachment.","headers":{"X-Export-Count":{"schema":{"type":"integer"},"description":"Number of records in export."},"X-Export-Type":{"schema":{"type":"string"},"description":"Entity type exported."},"Content-Disposition":{"schema":{"type":"string"},"description":"Attachment filename, e.g. `aletheia-compounds-2026-03-22T12-00-00.csv`."}},"content":{"text/csv":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object","properties":{"export":{"type":"object","properties":{"type":{"type":"string"},"count":{"type":"integer"},"generated_at":{"type":"string","format":"date-time"},"filters":{"type":"object"},"tier":{"type":"string"}}},"compounds":{"type":"array","items":{"$ref":"#/components/schemas/CompoundSynthesis"}},"materials":{"type":"array","items":{"type":"object"}},"products":{"type":"array","items":{"type":"object"}}}}}}},"400":{"description":"Invalid type or format parameter."},"401":{"description":"Invalid or missing API key."},"403":{"description":"API key tier insufficient — Developer or above required."},"429":{"description":"Rate limit exceeded (counts as 10 requests)."}},"x-codeSamples":[{"lang":"Shell","label":"cURL — CSV","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/export?type=compounds&format=csv\" \\\n  -o aletheia-compounds.csv"},{"lang":"Shell","label":"cURL — filtered CSV","source":"curl -H \"X-API-Key: YOUR_KEY\" \\\n  \"https://api.aletheia.holisticquality.io/api/export?type=compounds&format=csv&risk=high&context=human_child\" \\\n  -o high-risk-children.csv"},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.get(\n    \"https://api.aletheia.holisticquality.io/api/export\",\n    headers={\"X-API-Key\": \"YOUR_KEY\"},\n    params={\"type\": \"compounds\", \"format\": \"csv\"}\n)\nresp.raise_for_status()\nwith open(\"aletheia-compounds.csv\", \"wb\") as f:\n    f.write(resp.content)\nprint(f\"Exported {resp.headers['X-Export-Count']} compounds\")"},{"lang":"JavaScript","label":"JavaScript (Node)","source":"import { writeFileSync } from 'fs';\n\nconst resp = await fetch(\n  \"https://api.aletheia.holisticquality.io/api/export?type=compounds&format=csv\",\n  { headers: { \"X-API-Key\": \"YOUR_KEY\" } }\n);\nconst csv = await resp.text();\nwriteFileSync(\"aletheia-compounds.csv\", csv);\nconsole.log(`Exported ${resp.headers.get(\"X-Export-Count\")} compounds`);"}]}},"/api/webhooks":{"get":{"tags":["Webhooks"],"summary":"List your webhook subscriptions","description":"**Requires Developer+ API key.** Returns all webhooks registered to your API key.","operationId":"listWebhooks","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"responses":{"200":{"description":"List of webhooks","content":{"application/json":{"schema":{"type":"object","properties":{"webhooks":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"count":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Webhooks"],"summary":"Register a new webhook","description":"**Requires Developer+ API key.** Subscribe to compound update notifications. Max 10 webhooks per key. Webhook URLs must use HTTPS.","operationId":"createWebhook","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","example":"https://hooks.zapier.com/hooks/catch/12345/abcdef/"},"events":{"type":"array","items":{"type":"string","enum":["compound.updated","compound.risk_changed"]},"default":["compound.updated","compound.risk_changed"]},"compounds":{"type":"array","items":{"type":"string"},"description":"Compound IDs to watch, or [\"*\"] for all.","default":["*"]},"format":{"type":"string","enum":["json","slack"],"default":"json","description":"Use `slack` for Slack incoming webhooks (Block Kit format)."}}}}}},"responses":{"201":{"description":"Webhook registered","content":{"application/json":{"schema":{"type":"object","properties":{"webhook":{"$ref":"#/components/schemas/Webhook"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -X POST -H \"X-API-Key: YOUR_KEY\" -H \"Content-Type: application/json\" \\\n  -d '{\"url\":\"https://hooks.zapier.com/...\",\"events\":[\"compound.risk_changed\"],\"compounds\":[\"hq-c-org-000001\"]}' \\\n  \"https://api.aletheia.holisticquality.io/api/webhooks\""}]}},"/api/watchlist":{"get":{"tags":["Watchlist"],"summary":"List watched compounds with enrichment","description":"Returns your personal watchlist with enriched compound data (risk levels, CAS, hazard profile). Developer+ tier only.","operationId":"listWatchlist","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":100}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Watchlist with enriched compounds","content":{"application/json":{"schema":{"type":"object","properties":{"compounds":{"type":"array","items":{"type":"object"}},"count":{"type":"integer"},"limit":{"type":"integer","nullable":true},"updated":{"type":"string","nullable":true}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"post":{"tags":["Watchlist"],"summary":"Add compounds to watchlist","operationId":"addToWatchlist","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["compounds"],"properties":{"compounds":{"type":"array","items":{"type":"string"},"description":"Array of compound IDs"}}},"example":{"compounds":["hq-c-org-000001","hq-c-org-000033"]}}}},"responses":{"201":{"description":"Compounds added","content":{"application/json":{"schema":{"type":"object","properties":{"added":{"type":"array","items":{"type":"string"}},"watchlist":{"type":"object","properties":{"count":{"type":"integer"},"limit":{"type":"integer","nullable":true}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/watchlist/{compound_id}":{"delete":{"tags":["Watchlist"],"summary":"Remove a compound from watchlist","operationId":"removeFromWatchlist","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"compound_id","in":"path","required":true,"schema":{"type":"string","pattern":"^hq-c-[a-z]{3}-\\d{6}$"}}],"responses":{"200":{"description":"Compound removed","content":{"application/json":{"schema":{"type":"object","properties":{"removed":{"type":"string"},"remaining":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"description":"Compound not in watchlist"}}}},"/api/changelog":{"get":{"tags":["Changelog"],"summary":"Get regulatory and data change feed","description":"Returns a chronological feed of compound data changes — risk level updates, new regulatory classifications, property enrichments. Developer+ tier only.","operationId":"getChangelog","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date"},"description":"ISO date — filter changes after this date"},{"name":"compound_id","in":"query","schema":{"type":"string"},"description":"Filter to specific compound"},{"name":"type","in":"query","schema":{"type":"string"},"description":"Filter by change type"},{"name":"summary","in":"query","schema":{"type":"string","enum":["true"]},"description":"OAS-006: Return compact summary (useful for polling with since)"},{"name":"limit","in":"query","schema":{"type":"integer","default":50,"maximum":200}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}}],"responses":{"200":{"description":"Change feed","content":{"application/json":{"schema":{"type":"object","properties":{"changes":{"type":"array","items":{"type":"object","properties":{"compound_id":{"type":"string"},"compound_name":{"type":"string"},"type":{"type":"string","description":"Change type (e.g., risk_level_changed, classification_added)"},"field":{"type":"string"},"old_value":{},"new_value":{},"timestamp":{"type":"string","format":"date-time"},"notes":{"type":"string"}}}},"total":{"type":"integer"},"offset":{"type":"integer"},"limit":{"type":"integer"},"generated_at":{"type":"string","format":"date-time","description":"OAS-008: When the changelog was generated"},"has_more":{"type":"boolean","description":"OAS-008: Whether more entries exist beyond this page"}}}}}},"403":{"description":"Insufficient tier — requires Developer+ key"}}}},"/api/keys/usage":{"get":{"tags":["Keys"],"summary":"Get daily usage history","description":"Returns daily request counts for your API key over the specified number of days.","operationId":"getKeyUsage","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","default":7,"minimum":1,"maximum":30},"description":"Number of days of history (max 30)"}],"responses":{"200":{"description":"Usage history","content":{"application/json":{"schema":{"type":"object","properties":{"days":{"type":"integer"},"usage":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"requests":{"type":"integer"}}}},"tier":{"type":"string"},"limit":{"type":"integer"}}},"example":{"days":7,"usage":[{"date":"2026-04-01","requests":1234},{"date":"2026-03-31","requests":987}],"tier":"developer","limit":10000}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/keys/trial":{"post":{"tags":["Keys"],"summary":"Start a free 7-day Developer trial","description":"Provisions a trial API key with Developer tier access (10,000 requests/day) for 7 days. No credit card required. One trial per email address.","operationId":"startTrial","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address to send the trial key to"}}},"example":{"email":"you@example.com"}}}},"responses":{"201":{"description":"Trial key provisioned","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"tier":{"type":"string","example":"developer"},"trial":{"type":"boolean","example":true},"trial_days":{"type":"integer","example":7},"expires":{"type":"string","format":"date-time"},"key":{"type":"string","description":"The trial API key"},"dashboard":{"type":"string","format":"uri"}}}}}},"400":{"description":"Invalid email"},"409":{"description":"Trial already used for this email","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"upgrade_url":{"type":"string","format":"uri"}}}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/keys/resend":{"post":{"tags":["Keys"],"summary":"Retry email delivery for pending keys","description":"Re-sends the API key email for keys flagged as email_pending after a previous delivery failure. Always returns 200 to prevent email enumeration.","operationId":"resendKeyEmail","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}},"example":{"email":"you@example.com"}}}},"responses":{"200":{"description":"Resend attempted (always 200 to prevent enumeration)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","example":"If a pending key exists for that email, delivery has been retried."}}}}}},"400":{"description":"Invalid email"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/keys/erasure":{"post":{"tags":["Keys","Privacy"],"summary":"Request data erasure (GDPR Art. 17)","description":"Two-step email-verified data erasure. Step 1: POST with email only to receive a 6-digit verification code. Step 2: POST with email + code to permanently delete all personal data, API keys, webhooks, and usage records.","operationId":"requestErasure","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email associated with your API key(s)"},"code":{"type":"string","pattern":"^\\d{6}$","description":"6-digit verification code (Step 2 only)"}}},"examples":{"step1":{"summary":"Step 1: Request code","value":{"email":"you@example.com"}},"step2":{"summary":"Step 2: Confirm erasure","value":{"email":"you@example.com","code":"123456"}}}}}},"responses":{"200":{"description":"Code sent (step 1) or erasure complete (step 2)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"message":{"type":"string"},"next_step":{"type":"string"}},"description":"Step 1 response"},{"type":"object","properties":{"message":{"type":"string","example":"All personal data has been erased."},"keys_deleted":{"type":"integer"},"webhooks_deleted":{"type":"integer"},"privacy_policy":{"type":"string","example":"/api/privacy"}},"description":"Step 2 response"}]}}}},"400":{"description":"Invalid email or code format"},"403":{"description":"Invalid or expired verification code"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/watchlist/check":{"post":{"tags":["Watchlist"],"summary":"Batch check compounds against your watchlist","description":"Checks up to 100 compound IDs against your watchlist and returns which ones are on it.","operationId":"checkWatchlist","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["compounds"],"properties":{"compounds":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"Array of compound IDs to check"}}},"example":{"compounds":["hq-c-org-000001","hq-c-org-000033","hq-c-ino-000005"]}}}},"responses":{"200":{"description":"Check results","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"compound_id":{"type":"string"},"on_watchlist":{"type":"boolean"}}}},"watchlist_count":{"type":"integer"},"checked":{"type":"integer"},"on_watchlist":{"type":"integer","description":"Number of checked compounds that are on the watchlist"}}}}}},"400":{"description":"Invalid compounds array"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/fragrance":{"get":{"tags":["Fragrance"],"summary":"Fragrance catalog overview","description":"Returns summary info about the fragrance ingredient catalog including total ingredients, class count, and available endpoints.","operationId":"getFragranceOverview","responses":{"200":{"description":"Catalog overview","content":{"application/json":{"schema":{"type":"object","properties":{"total_ingredients":{"type":"integer"},"generated":{"type":"string"},"description":{"type":"string"},"classes":{"type":"integer"},"priority_distribution":{"type":"object"},"endpoints":{"type":"object"}}}}}}}}},"/api/fragrance/stats":{"get":{"tags":["Fragrance"],"summary":"Fragrance catalog statistics","operationId":"getFragranceStats","responses":{"200":{"description":"Catalog statistics","content":{"application/json":{"schema":{"type":"object","properties":{"total_ingredients":{"type":"integer"},"generated":{"type":"string"},"by_priority":{"type":"object"},"by_use_status":{"type":"object"},"classes":{"type":"integer"}}}}}}}}},"/api/fragrance/classes":{"get":{"tags":["Fragrance"],"summary":"List fragrance ingredient classes","operationId":"listFragranceClasses","responses":{"200":{"description":"List of classes","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"classes":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"ingredient_count":{"type":"integer"},"has_detailed_data":{"type":"boolean"},"summary":{"type":"string","nullable":true}}}}}}}}}}}},"/api/fragrance/class/{name}":{"get":{"tags":["Fragrance"],"summary":"Get fragrance class details","operationId":"getFragranceClass","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"},"description":"Class name (URL-encoded)"}],"responses":{"200":{"description":"Class details with ingredients","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Class not found"}}}},"/api/fragrance/search":{"get":{"tags":["Fragrance"],"summary":"Search fragrance ingredients","operationId":"searchFragrance","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search query (case-insensitive substring match)"}],"responses":{"200":{"description":"Search results (max 50)","content":{"application/json":{"schema":{"type":"object","properties":{"query":{"type":"string"},"count":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"class":{"type":"string"}}}}}}}}}}}},"/api/terms":{"get":{"tags":["Privacy"],"summary":"Terms of Use","description":"Returns the API terms of service. HTML by default, JSON with ?format=json.","operationId":"getTermsOfUse","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["html","json"]},"description":"Response format. Defaults to HTML."}],"responses":{"200":{"description":"Terms of use page","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"effective_date":{"type":"string"},"version":{"type":"string"},"url":{"type":"string"},"privacy_policy":{"type":"string"},"compliance":{"type":"string"},"sections":{"type":"array","items":{"type":"string"}}}}}}}}}},"/api/privacy":{"get":{"tags":["Privacy"],"summary":"Privacy policy (GDPR Art. 13)","description":"Returns the full privacy policy as an HTML page.","operationId":"getPrivacyPolicy","responses":{"200":{"description":"Privacy policy HTML page","content":{"text/html":{"schema":{"type":"string"}}}}}}},"/api/compliance":{"get":{"tags":["Privacy"],"summary":"Compliance & Data Processing Agreements (GDPR Art. 28)","description":"Returns DPA status, SCCs, and data transfer documentation for all sub-processors. HTML by default, JSON with ?format=json or Accept: application/json.","operationId":"getCompliance","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["html","json"]},"description":"Response format. Defaults to HTML."}],"responses":{"200":{"description":"Compliance documentation","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"_meta":{"type":"object","properties":{"version":{"type":"string"},"last_updated":{"type":"string"},"review_schedule":{"type":"string"},"next_review":{"type":"string"}}},"data_controller":{"type":"object","properties":{"entity":{"type":"string"},"contact":{"type":"string"},"jurisdiction":{"type":"string"}}},"processors":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"service":{"type":"string"},"jurisdiction":{"type":"string"},"dpa_status":{"type":"string","enum":["standard","custom","pending","not_required"]},"dpa_url":{"type":"string"},"sccs_required":{"type":"boolean"},"sccs_status":{"type":["string","null"]}}}}}}}}}}}}},"components":{"securitySchemes":{"ApiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key passed in the `X-API-Key` request header."},"ApiKeyQuery":{"type":"apiKey","in":"query","name":"api_key","description":"API key passed as a query parameter (less secure — prefer the header)."}},"parameters":{"CompoundId":{"name":"id","in":"path","required":true,"description":"Compound ID in format `hq-c-XXXX` (e.g., `hq-c-org-000001` for Glyphosate)","schema":{"type":"string","pattern":"^hq-c-[a-z]{3}-\\d{6}$","example":"hq-c-org-000001"}},"Page":{"name":"page","in":"query","description":"Page number (1-indexed)","schema":{"type":"integer","minimum":1,"default":1}},"Limit":{"name":"limit","in":"query","description":"Results per page. Public tier max: 50. Paid tier max: 200.","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error type"},"message":{"type":"string","description":"Human-readable description"},"hq_id":{"type":"string","description":"Compound ID (when relevant)"}},"required":["error"]},"RateLimitError":{"type":"object","properties":{"error":{"type":"string","example":"Rate limit exceeded"},"message":{"type":"string","example":"Daily limit of 10,000 requests reached. Resets at midnight UTC."},"rate_limit_reset":{"type":"integer","description":"Unix timestamp when limit resets"}}},"RootResponse":{"type":"object","properties":{"name":{"type":"string","example":"ALETHEIA"},"version":{"type":"string","example":"1.0.0"},"description":{"type":"string"},"tagline":{"type":"string"},"platform":{"type":"string"},"endpoints":{"type":"object"},"documentation":{"type":"string","format":"uri"},"data_enrichment":{"type":"object","properties":{"total_compounds":{"type":"integer"},"total_materials":{"type":"integer"},"total_products":{"type":"integer"},"enrichment_date":{"type":"string","format":"date"}}}}},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy"]},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"platform":{"type":"string"}}},"Meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"synthesis_version":{"type":"string"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"},"has_next":{"type":"boolean"},"has_prev":{"type":"boolean"}}},"CompoundSynthesis":{"type":"object","description":"Synthesized safety assessment for a compound in a given context","properties":{"hq_id":{"type":"string","example":"hq-c-org-000001"},"name":{"type":"string","example":"Glyphosate"},"context":{"type":"string","example":"human_adult"},"risk_level":{"type":"string","enum":["low","moderate","high","very_high","critical"],"example":"high"},"synthesis":{"type":"object","description":"Dimensional hazard analysis with scores and evidence"},"meta":{"$ref":"#/components/schemas/Meta"}}},"CompoundAllContexts":{"type":"object","description":"Synthesis results for all available contexts","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"all_contexts":{"type":"boolean","enum":[true]},"results":{"type":"object","additionalProperties":{"type":"object"},"description":"Context name → synthesis result"},"meta":{"type":"object","properties":{"n_contexts":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"}}}}},"CompoundLegacy":{"type":"object","description":"Raw safety data returned when synthesis is unavailable","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"context":{"type":"string"},"risk_level":{"type":["string","null"]},"schema":{"type":"string","enum":["legacy"]},"note":{"type":"string"},"data":{"type":["object","null"]},"meta":{"$ref":"#/components/schemas/Meta"}}},"CompoundRaw":{"type":"object","description":"Full compound data file (schema v3.2.0)","properties":{"hq_id":{"type":"string","example":"hq-c-org-000001"},"name":{"type":"string","example":"Glyphosate"},"crossrefs":{"type":"object","properties":{"cas":{"type":"string","example":"1071-83-6"},"pubchem_cid":{"type":"string"},"inchi_key":{"type":"string"},"dtxsid":{"type":"string"},"echa_ec":{"type":"string"},"unii":{"type":"string"},"chembl_id":{"type":"string"},"chebi_id":{"type":"string"},"wikidata_qid":{"type":"string"}}},"identity":{"type":"object","properties":{"iupac_name":{"type":"string"},"molecular_formula":{"type":"string"},"molecular_weight":{"type":"number"},"smiles":{"type":"string"}}},"hazard_profile":{"type":"string"},"safety":{"type":"object","description":"Nested contexts with risk levels and evidence"},"regulatory":{"type":"object","description":"Classifications, Prop 65, GHS data"},"found_in":{"type":"array","items":{"type":"object"}},"alternatives":{"type":"array","items":{"type":"object"}},"dose_response":{"type":"object","description":"NOAEL, LOAEL, LD50, LC50, RfD data"},"chemical_properties":{"type":"object"},"physical_properties":{"type":"object"},"properties":{"type":"object","description":"Environmental fate data"},"meta":{"type":"object","properties":{"status":{"type":"string"},"schema_version":{"type":"string"}}}}},"CompoundContextsResponse":{"type":"object","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"available_contexts":{"type":"array","items":{"type":"object","properties":{"context":{"type":"string","example":"human_adult"},"description":{"type":"string","example":"Adults aged 18+ in general population exposure scenarios"}}}},"meta":{"type":"object","properties":{"n_contexts":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"}}}}},"CasLookupResponse":{"type":"object","properties":{"hq_id":{"type":"string","example":"hq-c-org-000001"},"name":{"type":"string","example":"Glyphosate"},"cas":{"type":"string","example":"1071-83-6"},"hazard_profile":{"type":["string","null"]},"contexts":{"type":"array","items":{"type":"string"}},"endpoint":{"type":"string","example":"/api/compound/hq-c-org-000001"},"meta":{"type":"object","properties":{"lookup_type":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"CompoundListResponse":{"type":"object","properties":{"compounds":{"type":"array","items":{"type":"object","properties":{"hq_id":{"type":"string","example":"hq-c-org-000001"},"name":{"type":"string","example":"Glyphosate"},"cas":{"type":["string","null"]},"hazard_profile":{"type":["string","null"]},"risk_levels":{"type":"object","additionalProperties":{"type":"string"},"example":{"human_adult":"high","dog":"moderate"}},"contexts":{"type":"array","items":{"type":"string"}}}}},"pagination":{"$ref":"#/components/schemas/Pagination"},"filters":{"type":"object"},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"tier":{"type":"string"}}}}},"BatchResponse":{"type":"object","properties":{"results":{"type":"object","additionalProperties":{"oneOf":[{"type":"object","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"cas":{"type":["string","null"]},"hazard_profile":{"type":["string","null"]},"contexts":{"type":"array","items":{"type":"string"}},"risk_level":{"type":"string","description":"Present when context param is provided"},"context":{"type":"string"}}},{"type":"object","properties":{"error":{"type":"string","enum":["not_found"]}}}]}},"meta":{"type":"object","properties":{"requested":{"type":"integer"},"found":{"type":"integer"},"not_found":{"type":"array","items":{"type":"string"}},"context":{"type":["string","null"]},"timestamp":{"type":"string","format":"date-time"}}}}},"MaterialListResponse":{"type":"object","properties":{"materials":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"type":"object"}}},"MaterialRaw":{"type":"object","properties":{"hq_id":{"type":"string","example":"hq-m-str-000001"},"name":{"type":"string","example":"Polyvinyl Chloride (PVC)"},"type":{"type":"string","example":"polymer"},"aliases":{"type":"array","items":{"type":"string"}},"composition":{"type":"object","description":"Base compounds, additives, and contaminants with compound_id cross-references"},"behavior":{"type":"object","description":"Leaching, degradation, offgassing, and thermal behavior data"},"safety_summary":{"type":"object"},"common_uses":{"type":"array","items":{"type":"object"}},"alternatives":{"type":"array","items":{"type":"object"}},"meta":{"type":"object"}}},"ProductListResponse":{"type":"object","properties":{"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"hq-p-chd-000001"},"name":{"type":"string","example":"Baby bottles"},"category":{"type":"string","example":"children"},"product_tier":{"type":"string","example":"CHD","description":"Product tier: CHD (children), BDY (body), FOD (food), HOM (home), OUT (outdoor), PET (pet), WER (wearable), SPE (specialty)"},"risk_level":{"type":"string","example":"high","description":"Human-assigned overall risk level"},"derived_risk_level":{"type":"string","example":"moderate","description":"Algorithmically derived risk level from compound synthesis"},"synthesis_confidence":{"type":"number","example":0.71,"description":"Confidence score for derived risk level (0-1)"},"vulnerability_escalated":{"type":"boolean","example":true,"description":"Whether risk was escalated due to vulnerable population exposure"},"compound_count":{"type":"integer","example":6,"description":"Number of compounds in product formulation"}}}},"pagination":{"$ref":"#/components/schemas/Pagination"},"meta":{"type":"object"}}},"ProductProfile":{"type":"object","description":"Full product safety profile with pre-computed synthesis data","properties":{"hq_id":{"type":"string","example":"hq-p-chd-000001"},"name":{"type":"string","example":"Baby bottles"},"category":{"type":"object","properties":{"primary":{"type":"string"},"secondary":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}}}},"product_tier":{"type":"string","example":"CHD"},"overall_risk_level":{"type":"string","example":"high"},"description":{"type":"string"},"synthesis":{"type":"object","description":"Pre-computed risk synthesis from compound composition. compound_traces requires Developer+ API key.","properties":{"derived_risk_level":{"type":"string","example":"moderate"},"synthesis_confidence":{"type":"number","example":0.71},"synthesis_method":{"type":"string","example":"compound_composition"},"context_used":{"type":"string","example":"human_infant"},"vulnerability_escalated":{"type":"boolean","example":true},"escalation_reason":{"type":"string","example":"CHD tier product"},"compounds_resolved":{"type":"integer","example":5},"compounds_total":{"type":"integer","example":6},"compound_traces":{"type":"array","description":"Developer+ tier only. Per-compound risk contributions.","items":{"type":"object"}}}},"hazard_summary":{"type":"object"},"exposure":{"type":"object","description":"Exposure routes, users, duration, frequency, and scenarios"},"consumer_guidance":{"type":"object","description":"Red flags, green flags, alternatives, and safe use recommendations"},"regulatory":{"type":"object","description":"Applicable regulations, certifications, labeling requirements"},"lifecycle":{"type":"object","description":"Recyclability, disposal guidance, hazardous waste status, lifespan"},"formulation":{"type":"object","description":"Form, key ingredients, certifications"},"materials":{"type":"object","description":"Common, concerning, and preferred materials"},"compound_composition":{"type":"array","items":{"type":"object"},"description":"Compound references with roles and concentrations"},"identifiers":{"type":"object"},"brand_examples":{"type":"array","items":{"type":"object"}},"sources":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"schema_version":{"type":"string"},"last_updated":{"type":"string"},"timestamp":{"type":"string"}}}}},"ProductRaw":{"type":"object","description":"Raw unprocessed product JSON as stored in the database","properties":{"hq_id":{"type":"string","example":"hq-p-fod-000001"},"name":{"type":"string","example":"Roundup (Glyphosate-based herbicide)"},"type":{"type":"string"},"manufacturer":{"type":"string"},"compound_composition":{"type":"array","items":{"type":"object"},"description":"Compound references with roles and concentrations"},"hazard_summary":{"type":"object"},"safety":{"type":"object"},"consumer_guidance":{"type":"object","description":"Red flags, alternatives, and safe use recommendations"},"meta":{"type":"object"}}},"ContextsResponse":{"type":"object","properties":{"contexts":{"type":"array","items":{"type":"object","properties":{"context":{"type":"string","example":"human_adult"},"description":{"type":"string"},"aliases":{"type":"array","items":{"type":"string"}}}}},"grouped":{"type":"object","properties":{"human":{"type":"array","items":{"type":"object"}},"animal":{"type":"array","items":{"type":"object"}},"exposure_route":{"type":"array","items":{"type":"object"}},"environmental":{"type":"array","items":{"type":"object"}}}},"total":{"type":"integer"},"meta":{"type":"object"}}},"RegulatoryResponse":{"type":"object","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"cas":{"type":["string","null"]},"regulatory":{"type":"object","properties":{"classifications":{"type":"array","items":{"type":"object","properties":{"agency":{"type":"string","example":"IARC"},"classification":{"type":"string","example":"Group 2A - probably carcinogenic to humans"}}}},"count":{"type":"integer"},"summary":{"type":"object","properties":{"agencies":{"type":"array","items":{"type":"string"}},"agencies_count":{"type":"integer"},"by_agency":{"type":"object","additionalProperties":{"type":"integer"}},"classification_types":{"type":"object","additionalProperties":{"type":"integer"}}}}}},"meta":{"type":"object"}}},"AgenciesResponse":{"type":"object","properties":{"total_agencies":{"type":"integer"},"total_classifications":{"type":"integer"},"agencies":{"type":"array","items":{"type":"object","properties":{"agency":{"type":"string","example":"IARC"},"count":{"type":"integer"}}}},"meta":{"type":"object"}}},"ByAgencyResponse":{"type":"object","properties":{"agency":{"type":"string"},"total_matches":{"type":"integer"},"limit":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"cas":{"type":["string","null"]},"classification_count":{"type":"integer"},"classifications":{"type":"array","items":{"type":"object"}}}}},"meta":{"type":"object"}}},"FoundInResponse":{"type":"object","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"cas":{"type":["string","null"]},"type":{"type":["string","null"]},"found_in":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","example":"Food"},"examples":{"type":"array","items":{"type":"string"}},"notes":{"type":["string","null"]}}}},"summary":{"type":"object","properties":{"total_categories":{"type":"integer"},"total_exposure_sources":{"type":"integer"},"categories":{"type":"array","items":{"type":"object"}}}},"meta":{"type":"object"}}},"CategoriesResponse":{"type":"object","properties":{"total_categories":{"type":"integer"},"total_compounds_with_found_in":{"type":"integer"},"total_exposure_sources":{"type":"integer"},"categories":{"type":"array","items":{"type":"object","properties":{"category":{"type":"string","example":"Food"},"compounds":{"type":"integer"},"exposure_sources":{"type":"integer"}}}},"meta":{"type":"object"}}},"ByCategoryResponse":{"type":"object","properties":{"category":{"type":"string"},"total_matches":{"type":"integer"},"limit":{"type":"integer"},"results":{"type":"array","items":{"type":"object","properties":{"hq_id":{"type":"string"},"name":{"type":"string"},"cas":{"type":["string","null"]},"type":{"type":["string","null"]},"exposure_sources":{"type":"array","items":{"type":"string"}},"exposure_notes":{"type":["string","null"]}}}},"meta":{"type":"object"}}},"Webhook":{"type":"object","properties":{"id":{"type":"string","example":"wh_a1b2c3d4e5f6"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"type":"string","enum":["compound.updated","compound.risk_changed"]}},"compounds":{"type":"array","items":{"type":"string"},"description":"Compound IDs or [\"*\"] for all"},"format":{"type":"string","enum":["json","slack"]},"active":{"type":"boolean"},"last_triggered":{"type":["string","null"],"format":"date-time"},"failure_count":{"type":"integer"},"created":{"type":"string","format":"date-time"}}},"KeyStatusResponse":{"type":"object","properties":{"tier":{"type":"string","enum":["developer","pro","enterprise"],"description":"Subscription tier. Trial keys return \"developer\" with trial=true."},"active":{"type":"boolean"},"created":{"type":"string","format":"date-time"},"trial":{"type":"boolean","description":"Whether this is a trial key"},"trial_expires":{"type":["string","null"],"format":"date-time","description":"ISO date when trial expires"},"email_masked":{"type":["string","null"],"description":"Masked email (e.g., \"tes***@example.com\")"},"usage":{"type":"object","properties":{"today":{"type":"integer"},"limit":{"type":["integer","null"],"description":"null for enterprise (unlimited)"},"remaining":{"type":["integer","null"]},"resets":{"type":"string"}}}}},"SearchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"entity_type":{"type":"string","enum":["compound","product","material"],"description":"Type of matched entity"},"id":{"type":"string","description":"Entity ID (e.g., hq-c-org-000001, hq-m-str-000001, hq-p-fod-000001)"},"name":{"type":"string","description":"Entity name"},"score":{"type":"integer","minimum":0,"maximum":100,"description":"Relevance score"},"cas":{"type":["string","null"],"description":"CAS number (compounds only)"},"type":{"type":["string","null"],"description":"Compound type or product type"},"category":{"type":["string","null"],"description":"Category classification"},"hazard_profile":{"type":["string","null"],"description":"Hazard classification (compounds only)"}},"required":["entity_type","id","name","score"]},"description":"Array of search results sorted by relevance score (highest first)"},"total":{"type":"integer","description":"Total number of matches"},"query":{"type":"string","description":"The search query that was executed"},"limit":{"type":"integer","description":"Results per page"},"offset":{"type":"integer","description":"Number of results skipped"},"has_more":{"type":"boolean","description":"Whether more results exist beyond the current page"},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"tier":{"type":"string","enum":["public","developer","pro","enterprise"]}}}}},"FilterResponse":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Compound ID (e.g., hq-c-org-000001)"},"name":{"type":"string","description":"Compound name"},"cas":{"type":["string","null"],"description":"CAS Registry Number"},"type":{"type":["string","null"],"description":"Compound functional type"},"category":{"type":["string","null"],"description":"Category classification"},"hazard_profile":{"type":["string","null"],"description":"Hazard profile classification"},"risk_levels":{"type":"object","additionalProperties":{"type":"string"},"description":"Risk levels across all available contexts","example":{"human_adult":"high","human_child":"very_high","dog":"moderate"}},"contexts":{"type":"array","items":{"type":"string"},"description":"List of available safety contexts for this compound"}},"required":["id","name"]},"description":"Filtered compound results sorted alphabetically by name"},"total":{"type":"integer","description":"Total number of compounds matching all filters"},"limit":{"type":"integer","description":"Results per page"},"offset":{"type":"integer","description":"Number of results skipped"},"has_more":{"type":"boolean","description":"Whether more results exist beyond the current page"},"filters_applied":{"type":"object","description":"All filters that were applied to produce these results","additionalProperties":true,"example":{"risk":"high","context":"human_adult","type":"herbicide"}},"meta":{"type":"object","properties":{"timestamp":{"type":"string","format":"date-time"},"tier":{"type":"string","enum":["public","developer","pro","enterprise"]}}}}}},"responses":{"BadRequest":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"API key required or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"API key required","message":"This endpoint requires a Developer or Pro key. Get one at https://aletheia.holisticquality.io/pricing"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Compound not found","hq_id":"hq-c-org-009999","message":"No compound found with ID: hq-c-org-009999"}}}},"MethodNotAllowed":{"description":"HTTP method not allowed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Method not allowed"}}}},"RateLimited":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}},"headers":{"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining today"}}},"InternalError":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Internal server error","message":"An unexpected error occurred. Please try again."}}}}}}}