{"openapi":"3.1.0","info":{"title":"ALETHEIA Safety Reference API","version":"1.4.5","description":"Chemical and product safety reference API aggregating public regulatory and scientific sources. Covers 1,886 compounds, 959 materials, and 1,287 consumer products with tier labels drawn from published classifications. Returns aggregated safety records across **19 exposure contexts** — 8 human life-stages (adult, child, teen, infant, pregnant, nursing, elderly, immunocompromised), domestic dog and cat, 5 exposure routes (dermal, inhalation, ingestion, ocular, occupational), plus environmental, aquatic-life, terrestrial-wildlife, and pollinator contexts — along with regulatory classifications from 15+ primary agencies-of-record (IARC, EPA, EU CLP, ECHA, NTP, CalEPA, FDA, OEHHA, Health Canada, OSHA/NIOSH, WHO, etc.), exposure source mapping, and published dose-response data.\n\n> *Note on agency counts:* \"15+ agencies\" refers to primary regulators curated as agencies-of-record. The full `regulatory-agencies.json` index lists ~200 distinct attribution strings, including EPA CompTox sub-program designations (e.g., `EPA CTX / IRIS`, `EPA CTX / NTP RoC`) that share the EPA institutional source but represent distinct database lineages.\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** — open to all tiers. Per-request caps: Public up to 10, Developer up to 50, Pro up to 100, Enterprise up to 100. (RapidAPI tier names: Basic 10, Pro 50, Ultra 100.) The `synthesize=true` option requires a Developer key or higher.\n```bash\ncurl -H \"X-API-Key: YOUR_KEY\" \\\n \"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[\"risk_level\"], compound[\"risk_profile\"][\"confidence\"][\"mean\"])\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');\nconsole.log(compound.risk_level, compound.risk_profile.confidence.mean);\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 | $79/mo |\n| Pro | 100,000 | $299/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\nMost responses include the following rate-limit headers:\n\n- `X-RateLimit-Limit` — daily request quota for your tier\n- `X-RateLimit-Remaining` — requests left in the current daily window\n- `X-RateLimit-Reset` — Unix timestamp (milliseconds) when the daily counter resets (00:00 UTC)\n- `X-API-Tier` — your current tier (`public`, `developer`, `pro`, or `enterprise`)\n- `X-Usage-Warning` — present when usage crosses 80% of the daily quota\n- `X-Upgrade-URL` — link to the pricing page when you are approaching or have exceeded a paid-tier limit\n\n**Enterprise tier exception:** Enterprise customers have an unlimited daily and burst quota, so `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `X-Usage-Warning`, and `X-Upgrade-URL` are not emitted for enterprise traffic. `X-API-Tier: enterprise` is still returned on every response.\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.\n\n## Data Quality and Disclaimer Fields\n\nEvery export response includes envelope-level disclaimer fields (`_notice`, `_disclaimer_url`) — see the `EnvelopeNotice` component schema. The `_notice` text is the short-form reference-not-advice statement that mirrors GET /api/disclaimer?format=json (`envelope_notice` field).\n\nIndividual compound records may also carry a `data_quality` array when one or more structural fields are under chemist review — see the `DataQualityAnnotation` component schema. When present, the affected fields (SMILES, InChI, InChIKey, exact mass, molecular formula) carry the sentinel string `[under-review:SCI-DAT-01]` in place of their values; CAS, name, IUPAC, and synonyms on annotated records remain authoritative. Consumers should route around the sentinel for structural-identity-dependent downstream work and check `data_quality[].finding` for the registry reference.\n\nThe full Disclaimer (including all warranty, liability, and \"reference data, not professional advice\" framing) is at . Use of the Service constitutes acceptance — see Terms of Service for the binding text.","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 records aggregated across multiple exposure contexts"},{"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"},{"name":"Fragrance","description":"Fragrance compound records — allergens, musks, and aroma chemicals with classification and search"}],"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/freshness":{"get":{"tags":["Reference"],"summary":"Data freshness snapshot","description":"Public snapshot of how current the ALETHEIA dataset is — entity counts, staleness buckets (current/aging/stale/very_stale/never), and the timestamp of the most recent freshness check. Refreshed daily at 06:00 UTC by an internal cron. 30-minute edge cache.","operationId":"getFreshness","responses":{"200":{"description":"Freshness snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"snapshot_generated_at":{"type":"string","format":"date-time","nullable":true,"description":"When the build-time freshness summary was generated"},"last_checked_at":{"type":"string","format":"date-time","nullable":true,"description":"When the daily freshness cron last ran"},"deploy_age_days":{"type":"integer","nullable":true,"description":"Days since the most recent deploy generated a freshness summary"},"deploy_stale":{"type":"boolean","nullable":true,"description":"True if deploy_age_days >= 7 (data may be going stale)"},"entities":{"type":"object","description":"Per-entity staleness buckets","properties":{"compounds":{"type":"object","nullable":true},"materials":{"type":"object","nullable":true},"products":{"type":"object","nullable":true}}},"totals":{"type":"object","properties":{"entities":{"type":"integer","nullable":true,"description":"Total entities in the dataset"},"current":{"type":"integer","nullable":true,"description":"Entities reviewed in the last 90 days"},"stale_or_worse":{"type":"integer","nullable":true,"description":"Entities older than 6 months or never reviewed"}}},"regulatory_stale_count":{"type":"integer","description":"Count of regulatory-sensitive entities that are stale (identities redacted from public payload)"},"source":{"type":"string","enum":["redis","build"],"description":"Whether the snapshot came from the daily Redis cache or the build-time file fallback"}}},"example":{"snapshot_generated_at":"2026-04-20T00:00:00.000Z","last_checked_at":"2026-04-21T06:00:12.000Z","deploy_age_days":1,"deploy_stale":false,"entities":{"compounds":{"total":1879,"current":1650,"aging":150,"stale":50,"very_stale":20,"never":9},"materials":{"total":959,"current":820,"aging":90,"stale":40,"very_stale":9,"never":0},"products":{"total":1262,"current":1100,"aging":100,"stale":50,"very_stale":12,"never":0}},"totals":{"entities":4100,"current":3570,"stale_or_worse":190},"regulatory_stale_count":3,"source":"redis"}}}},"503":{"description":"Freshness summary not yet generated (fresh deploy, cron hasn't run, and fallback file missing)"}}}},"/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 aggregated safety record for a compound","description":"Returns the aggregated safety record for the given compound and context. Regulatory classifications are normalized across agencies, aggregated into multi-field risk signals across several dimensions, and returned as a `risk_level` tier label with supporting evidence fields.\n\n**No API key required** — this is a free endpoint.\n\nIf the aggregated record is unavailable (compound lacks normalizable regulatory data), returns raw safety data with `schema: \"legacy\"`.","operationId":"getCompound","parameters":[{"$ref":"#/components/parameters/CompoundId"},{"name":"context","in":"query","description":"Safety context for the aggregated record (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 aggregated results for all available contexts at once.","schema":{"type":"string","enum":["true"]}}],"responses":{"200":{"description":"Aggregated safety record (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 aggregated record 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 (unaggregated)","description":"Returns the full compound data file as stored, without the aggregated risk record. 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 — multiple compounds in one request (tier-dependent cap)","description":"Batch-fetch multiple compounds in a single request. Open to all tiers. Per-request caps: Public up to 10, Developer up to 50, Pro up to 100, Enterprise up to 100 (RapidAPI: Basic 10 / Pro 50 / Ultra 100). Accepts both `hq_id` values and CAS numbers; CAS numbers are auto-resolved and reported under `meta.cas_resolved`. The `synthesize=true` option requires a Developer key or higher.","operationId":"batchCompounds","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"parameters":[{"name":"ids","in":"query","required":true,"description":"Comma-separated compound IDs or CAS numbers. Per-request cap is tier-dependent: Developer up to 20, Pro up to 50, Enterprise up to 100. Requests above your cap return `400 \"Too many compounds\"`.","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});"}]},"post":{"tags":["Compounds"],"summary":"Batch lookup (POST) — JSON body, preferred for >30 IDs","description":"POST variant of batch lookup. Prefer POST over GET when your ID list is large (>30 IDs) — GET query strings hit URL length limits, while POST bodies are bounded only by the tier cap (Public 10 / Developer 50 / Pro 100 / Enterprise 100; RapidAPI: Basic 10 / Pro 50 / Ultra 100). Same tier gating as GET. Accepts both `hq_id` values and CAS numbers; CAS numbers are auto-resolved.","operationId":"batchCompoundsPost","security":[{"ApiKeyHeader":[]},{"ApiKeyQuery":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["compounds"],"properties":{"compounds":{"type":"array","description":"Compound IDs or CAS numbers. Per-request cap is tier-dependent: Developer up to 20, Pro up to 50, Enterprise up to 100.","items":{"type":"string"},"example":["hq-c-org-000001","hq-c-org-000033","hq-c-org-000100"]},"context":{"type":"string","description":"Extract `risk_level` for this context on each compound.","example":"human_adult"},"synthesize":{"type":"boolean","description":"Populate the full aggregated `synthesis` block per compound. Costs 2 credits each; max 10 records per request.","default":false},"detail":{"type":"string","description":"`summary` (default) returns core fields; `full` returns complete compound data.","enum":["summary","full"],"default":"summary"}}}}}},"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"},"413":{"$ref":"#/components/responses/BadRequest"},"415":{"$ref":"#/components/responses/BadRequest"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalError"}},"x-code-samples":[{"lang":"cURL","label":"cURL","source":"curl -X POST \"https://api.aletheia.holisticquality.io/api/compounds/batch\" \\\n -H \"X-API-Key: YOUR_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"compounds\":[\"hq-c-org-000001\",\"hq-c-org-000033\",\"hq-c-org-000100\"],\"context\":\"dog\"}'"},{"lang":"Python","label":"Python","source":"import requests\n\nresp = requests.post(\n \"https://api.aletheia.holisticquality.io/api/compounds/batch\",\n headers={\"X-API-Key\": \"YOUR_KEY\"},\n json={\n \"compounds\": [\"hq-c-org-000001\", \"hq-c-org-000033\", \"hq-c-org-000100\"],\n \"context\": \"dog\",\n },\n)\ndata = resp.json()\nfor cid, info in data[\"results\"].items():\n print(f\"{cid}: {info.get('name', info.get('error'))}\")"},{"lang":"JavaScript","label":"JavaScript (fetch)","source":"const resp = await fetch(\n \"https://api.aletheia.holisticquality.io/api/compounds/batch\",\n {\n method: \"POST\",\n headers: {\n \"X-API-Key\": \"YOUR_KEY\",\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n compounds: [\"hq-c-org-000001\", \"hq-c-org-000033\", \"hq-c-org-000100\"],\n context: \"dog\",\n }),\n }\n);\nconst { results, meta } = await resp.json();\nconsole.log(`Found ${meta.found} of ${meta.requested}`);"}]}},"/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":"Aggregated risk level tiers + 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 aggregated product safety profile","description":"Returns the full product safety profile aggregating public regulatory and scientific sources: compound composition, hazard summary, exposure assessment, regulatory status, handling guidance, and lifecycle data. The `synthesis` block contains aggregated risk level tiers derived from the product's compound composition. Free tier: full profile except `compound_traces`. Developer+ tier: includes `compound_traces` showing per-compound risk contributions.\n\n**Note on `brand_examples[]`:** when present, the `brand_examples[]` array lists representative branded products of the category. Concerning ingredients listed in `materials.concerning[]` apply to the category, not necessarily to every named brand. The `brand_examples_disclaimer` sibling field surfaces this framing inline in every response.","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 aggregated product safety profile","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/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 `` tag — no iframe, no API key, CDN-cacheable (24h).\n\n**Embed example:**\n```html\n\n \"ALETHEIA\n\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":"\"Safety"},{"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/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/release-notes":{"get":{"tags":["Reference"],"summary":"API release notes — security updates, header contract, new endpoints","description":"Customer-facing release notes for the API surface itself (not the compound data feed). Returns HTML by default; pass `?format=json` for a structured version list or `?format=markdown` for the raw source. Public — no key required. For per-compound data changes see `/api/changelog`.","operationId":"getReleaseNotes","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["html","json","markdown"],"default":"html"},"description":"Response format"}],"responses":{"200":{"description":"Release notes","content":{"text/html":{"schema":{"type":"string"}},"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string"},"canonical_url":{"type":"string","format":"uri"},"source_file":{"type":"string"},"data_changelog":{"type":"string","format":"uri"},"latest":{"type":"object","nullable":true,"properties":{"date":{"type":"string","format":"date"},"title":{"type":"string","nullable":true},"body":{"type":"string"}}},"versions":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"title":{"type":"string","nullable":true},"body":{"type":"string"}}}}}}}}}}}},"/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/disclaimer":{"get":{"tags":["Privacy"],"summary":"Disclaimer","description":"Returns the ALETHEIA Disclaimer — the canonical \"reference data, not professional advice\" document, incorporated by reference into both Terms of Service and Privacy Policy. HTML by default, JSON with ?format=json. The JSON `envelope_notice` field exactly matches the `_notice` field that every export response carries (T-2 board memo 2026-05-22).","operationId":"getDisclaimer","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["html","json"]},"description":"Response format. Defaults to HTML."}],"responses":{"200":{"description":"Disclaimer page","content":{"text/html":{"schema":{"type":"string"}},"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","example":"Disclaimer — ALETHEIA"},"version":{"type":"string","example":"1.0"},"effective_date":{"type":"string","example":"2026-05-22"},"last_reviewed":{"type":"string","example":"2026-05-22"},"canonical_url":{"type":"string","format":"uri"},"terms_url":{"type":"string","format":"uri"},"privacy_url":{"type":"string","format":"uri"},"operator":{"type":"string","example":"Holistic Quality LLC"},"envelope_notice":{"type":"string","description":"Short-form reference-not-advice text. Mirrored verbatim in the `_notice` field of every export response envelope."}}}}}}}}},"/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":{"EnvelopeNotice":{"type":"object","description":"Disclaimer fields included in the export response envelope. The `_notice` text mirrors the short-form text at GET /api/disclaimer?format=json (`envelope_notice` field), guaranteeing the legal copy on /disclaimer and the API envelope cannot drift. T-2 board memo 2026-05-22.","properties":{"_notice":{"type":"string","description":"Reference-not-advice notice. Always present on export responses; matches /api/disclaimer envelope_notice exactly.","example":"ALETHEIA output is reference data, not professional advice. Not a substitute for primary agency sources or qualified professionals. See https://aletheia.holisticquality.io/disclaimer."},"_disclaimer_url":{"type":"string","format":"uri","description":"Canonical link to the full Disclaimer document.","example":"https://aletheia.holisticquality.io/disclaimer"}}},"DataQualityAnnotation":{"type":"object","description":"Per-field data-quality annotation attached to a compound record when one or more structural fields are under chemist review. When present, the affected fields (SMILES, InChI, InChIKey, exact mass, molecular formula) carry the sentinel string `[under-review:SCI-DAT-01]` in place of their values; CAS, name, IUPAC, and synonyms remain authoritative. See finding `aletheia-api/2026-05-04/SCI-DAT-01` (chemical-identity contamination, open chemist queue).","properties":{"field":{"type":"string","description":"Dotted path or flat column name of the affected field.","example":"identity.smiles"},"status":{"type":"string","enum":["under_review"],"description":"Quality status. Only `under_review` is currently emitted."},"finding":{"type":"string","example":"SCI-DAT-01","description":"Registry finding identifier. Tie back to `tracking/SCI-DAT-01-CHEMIST-QUEUE.md`."},"sources":{"type":"array","items":{"type":"string"},"description":"Provenance tags for why this field is flagged.","example":["SCI-DAT-01"]},"reference":{"type":"string","description":"Operator-facing chemist queue document path.","example":"tracking/SCI-DAT-01-CHEMIST-QUEUE.md"}},"required":["field","status","finding"]},"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":"Aggregated safety record 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":"Multi-dimensional hazard breakdown with per-dimension scores and source evidence"},"meta":{"$ref":"#/components/schemas/Meta"}}},"CompoundAllContexts":{"type":"object","description":"Aggregated records 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 → aggregated record"},"meta":{"type":"object","properties":{"n_contexts":{"type":"integer"},"timestamp":{"type":"string","format":"date-time"}}}}},"CompoundLegacy":{"type":"object","description":"Raw safety data returned when the aggregated record 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","object","null"],"description":"Hazard classification. Either a severity string (e.g., 'hazardous', 'moderate', 'low'; 1,355 compounds) or a structured object with boolean hazard flags (skin_sensitizer, allergen, acute_toxicity, environmental, etc.; 524 compounds). String and object forms are both valid; consumers should handle both."},"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","object","null"],"description":"Hazard classification. Either a severity string (e.g., 'hazardous', 'moderate', 'low'; 1,355 compounds) or a structured object with boolean hazard flags (skin_sensitizer, allergen, acute_toxicity, environmental, etc.; 524 compounds). String and object forms are both valid; consumers should handle both."},"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","object","null"],"description":"Hazard classification. Either a severity string (e.g., 'hazardous', 'moderate', 'low'; 1,355 compounds) or a structured object with boolean hazard flags (skin_sensitizer, allergen, acute_toxicity, environmental, etc.; 524 compounds). String and object forms are both valid; consumers should handle both."},"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","object","null"],"description":"Hazard classification. Either a severity string (e.g., 'hazardous', 'moderate', 'low'; 1,355 compounds) or a structured object with boolean hazard flags (skin_sensitizer, allergen, acute_toxicity, environmental, etc.; 524 compounds). String and object forms are both valid; consumers should handle both."},"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":"Aggregated risk level derived from compound composition"},"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 aggregated product safety profile","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":"Aggregated risk record derived 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":"Aggregated red flags, green flags, alternatives, and safe-use notes from source datasets"},"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"},"description":"Representative branded products of this category. Concerning ingredients listed in materials.concerning[] apply to the category, not necessarily to every named brand. See brand_examples_disclaimer."},"brand_examples_disclaimer":{"type":["string","null"],"description":"Category-vs-brand-allegation framing surfaced when brand_examples[] is non-empty. States that listed brands are category exemplars, not products shown to contain the listed concerns."},"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","object","null"],"description":"Hazard classification (compounds only) — string severity or structured object with boolean hazard flags. See CompoundHazardProfile schema for object shape."}},"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","object","null"],"description":"Hazard profile classification — string severity or structured object with boolean hazard flags."},"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. Implement exponential backoff on 429 responses (recommended: 1s initial delay, 2x multiplier, jitter, max 5 retries). Enterprise tier (X-API-Tier: enterprise) has unlimited quota and will never return this status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitError"}}},"headers":{"X-RateLimit-Limit":{"schema":{"type":"integer"},"description":"Daily request quota for your tier. Omitted for enterprise."},"X-RateLimit-Remaining":{"schema":{"type":"integer"},"description":"Requests remaining in the current daily window. Omitted for enterprise."},"X-RateLimit-Reset":{"schema":{"type":"integer"},"description":"Unix timestamp (milliseconds) when the daily counter resets (00:00 UTC). Omitted for enterprise."},"X-API-Tier":{"schema":{"type":"string","enum":["public","developer","pro","enterprise"]},"description":"Your current tier. Returned on every response, including enterprise."},"X-Usage-Warning":{"schema":{"type":"string"},"description":"Present when daily usage crosses 80% of quota. Omitted for enterprise."},"X-Upgrade-URL":{"schema":{"type":"string","format":"uri"},"description":"Link to the pricing page when approaching or exceeding a paid-tier limit. Omitted for enterprise."},"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait before retrying. Set on 429 burst-limit responses."}}},"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."}}}}}}}