wotann 0.5.0 → 0.5.39

package/skills/scientific/database-lookup/references/cbioportal.md

@@ -0,0 +1,206 @@
+# cBioPortal API
+
+## Base URL
+```
+https://www.cbioportal.org/api
+```
+
+## Auth
+No authentication for the public instance. Private/institutional instances (e.g. `genie.cbioportal.org`) require a data access token via `Authorization: Bearer <token>` header.
+
+## Common Headers
+```
+Accept: application/json
+Content-Type: application/json
+```
+
+## Common Query Parameters
+
+Most list endpoints support these:
+
+| Parameter | Type | Description | Default |
+|---|---|---|---|
+| `projection` | string | Detail level: `ID`, `SUMMARY`, `DETAILED`, `META` | `SUMMARY` |
+| `pageNumber` | int | Zero-based page index | `0` |
+| `pageSize` | int | Results per page | `10000000` |
+| `sortBy` | string | Property to sort by | varies |
+| `direction` | string | `ASC` or `DESC` | `ASC` |
+
+## Key Endpoints
+
+### Studies
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/studies` | List all cancer studies |
+| GET | `/studies/{studyId}` | Get a single study |
+| POST | `/studies/fetch` | Fetch multiple studies by ID |
+
+Example:
+```
+GET https://www.cbioportal.org/api/studies?projection=SUMMARY&pageSize=10
+GET https://www.cbioportal.org/api/studies/brca_tcga
+```
+
+Response fields: `studyId`, `name`, `description`, `cancerTypeId`, `pmid`, `citation`, `allSampleCount`, `referenceGenome`, `publicStudy`, `importDate`
+
+### Cancer Types
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/cancer-types` | List all cancer types |
+| GET | `/cancer-types/{cancerTypeId}` | Get one cancer type |
+
+Response fields: `cancerTypeId`, `name`, `shortName`, `dedicatedColor`, `parent`
+
+### Genes
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/genes` | List all genes (paginated) |
+| GET | `/genes/{geneId}` | Gene by Hugo symbol or Entrez ID |
+| GET | `/genes/{geneId}/aliases` | Gene aliases |
+| POST | `/genes/fetch` | Fetch multiple genes |
+
+Example:
+```
+GET https://www.cbioportal.org/api/genes/TP53
+```
+Response: `{"entrezGeneId": 7157, "hugoGeneSymbol": "TP53", "type": "protein-coding"}`
+
+### Molecular Profiles
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/molecular-profiles` | All profiles across all studies |
+| GET | `/studies/{studyId}/molecular-profiles` | Profiles in a study |
+| GET | `/molecular-profiles/{molecularProfileId}` | Single profile |
+
+Profile types (`molecularAlterationType`): `MUTATION_EXTENDED`, `COPY_NUMBER_ALTERATION`, `MRNA_EXPRESSION`, `PROTEIN_LEVEL`, `METHYLATION`
+
+Example:
+```
+GET https://www.cbioportal.org/api/studies/brca_tcga/molecular-profiles
+```
+
+### Mutations
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/molecular-profiles/{profileId}/mutations` | Mutations in a profile |
+| POST | `/molecular-profiles/{profileId}/mutations/fetch` | Filtered mutation query |
+| POST | `/mutations/fetch` | Multi-profile mutation fetch |
+
+Parameters for GET:
+| Parameter | Type | Description |
+|---|---|---|
+| `sampleListId` | string | Sample list to query (e.g. `brca_tcga_all`) |
+| `entrezGeneId` | int | Filter by gene |
+| `projection` | string | `SUMMARY`, `DETAILED`, `ID`, `META` |
+
+Example — TP53 mutations in TCGA breast cancer:
+```
+GET https://www.cbioportal.org/api/molecular-profiles/brca_tcga_mutations/mutations?sampleListId=brca_tcga_all&entrezGeneId=7157&projection=DETAILED
+```
+
+POST body for multi-gene fetch:
+```json
+{
+  "sampleListId": "brca_tcga_all",
+  "entrezGeneIds": [7157, 672]
+}
+```
+
+Response fields: `entrezGeneId`, `sampleId`, `patientId`, `proteinChange`, `mutationType`, `mutationStatus`, `chr`, `startPosition`, `endPosition`, `referenceAllele`, `variantAllele`, `variantType`, `ncbiBuild`, `tumorAltCount`, `tumorRefCount`
+
+### Copy Number Alterations
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/molecular-profiles/{profileId}/discrete-copy-number` | CNA data |
+| POST | `/molecular-profiles/{profileId}/discrete-copy-number/fetch` | Filtered CNA query |
+| POST | `/discrete-copy-number/fetch` | Multi-profile CNA fetch |
+
+### Molecular Data (expression, methylation)
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/molecular-profiles/{profileId}/molecular-data` | Expression/methylation data |
+| POST | `/molecular-data/fetch` | Multi-profile molecular data fetch |
+
+### Clinical Data
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/studies/{studyId}/clinical-data` | Clinical data for a study |
+| POST | `/clinical-data/fetch` | Multi-study clinical data |
+| GET | `/studies/{studyId}/clinical-attributes` | Available clinical attributes |
+
+Parameters for GET:
+| Parameter | Type | Description |
+|---|---|---|
+| `clinicalDataType` | string | `PATIENT` or `SAMPLE` |
+| `attributeId` | string | e.g. `OS_STATUS`, `OS_MONTHS`, `CANCER_TYPE` |
+
+Example:
+```
+GET https://www.cbioportal.org/api/studies/brca_tcga/clinical-data?clinicalDataType=PATIENT&attributeId=OS_STATUS&projection=SUMMARY
+```
+
+### Patients & Samples
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/studies/{studyId}/patients` | Patients in a study |
+| GET | `/studies/{studyId}/samples` | Samples in a study |
+| POST | `/patients/fetch` | Multi-study patient fetch |
+| POST | `/samples/fetch` | Multi-study sample fetch |
+
+### Sample Lists
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/studies/{studyId}/sample-lists` | Predefined sample groups |
+| GET | `/sample-lists/{sampleListId}` | Single sample list |
+
+### Gene Panels
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/gene-panels` | All gene panels |
+| GET | `/gene-panels/{genePanelId}` | Panel details with gene list |
+| POST | `/gene-panel-data/fetch` | Which panels cover which samples |
+
+### Treatments
+
+| Method | Endpoint | Description |
+|---|---|---|
+| POST | `/treatments/patient` | Patient-level treatment data |
+| POST | `/treatments/sample` | Sample-level treatment data |
+
+### System
+
+| Method | Endpoint | Description |
+|---|---|---|
+| GET | `/health` | Server health check |
+| GET | `/info` | Portal version, DB schema version |
+
+## Typical Workflow
+
+1. **Find studies**: `GET /studies` — browse available cancer studies, get `studyId` values
+2. **Get molecular profiles**: `GET /studies/{studyId}/molecular-profiles` — find profile IDs (e.g. `brca_tcga_mutations`, `brca_tcga_gistic`)
+3. **Get sample lists**: `GET /studies/{studyId}/sample-lists` — find sample list IDs (e.g. `brca_tcga_all`, `brca_tcga_sequenced`)
+4. **Query data**: Use the profile ID and sample list ID to fetch mutations, CNA, expression, or clinical data
+
+## Rate Limits
+
+No published rate limits. Be courteous — avoid hammering with many concurrent requests. For bulk data needs, cBioPortal offers downloadable datasets at https://docs.cbioportal.org/downloads/.
+
+## Tips
+
+- **Study IDs** follow a pattern: `{cancer_type}_{source}` (e.g. `brca_tcga`, `luad_tcga`, `prad_mskcc_2017`)
+- **Molecular profile IDs** extend the study ID: `{studyId}_mutations`, `{studyId}_gistic`, `{studyId}_rna_seq_v2_mrna`
+- Use `projection=DETAILED` to get the richest response including nested objects
+- POST `/fetch` endpoints are for batch queries across multiple studies, genes, or samples — they're the most flexible way to query
+- Gene lookup accepts both Hugo symbols (`TP53`) and Entrez IDs (`7157`)
+- The Swagger UI at https://www.cbioportal.org/api/swagger-ui/index.html documents every endpoint interactively

package/skills/scientific/database-lookup/references/census.md

@@ -0,0 +1,251 @@
+# US Census Bureau API Reference
+
+## Overview
+The US Census Bureau API provides access to hundreds of datasets including the American Community Survey (ACS), Decennial Census, Economic Census, Population Estimates, and more. It is the primary source for US demographic, social, economic, and housing data.
+
+## Base URL
+```
+https://api.census.gov/data
+```
+
+## Authentication
+- **API Key: REQUIRED (free).** Register at https://api.census.gov/data/key_signup.html
+- Pass as query parameter: `&key=YOUR_KEY`
+- Requests without a key are throttled to ~500/day. With a key, limits are much higher.
+
+## Rate Limits
+- Without key: approximately 500 requests per day.
+- With key: up to 500 requests per day per IP is the documented soft limit, but in practice the key grants significantly more.
+- No formal per-minute rate limit documented; keep automated requests to a few per second.
+
+---
+
+## Key Datasets and URL Patterns
+
+The general URL pattern is:
+```
+https://api.census.gov/data/{year}/{dataset}?get={variables}&for={geography}&key=YOUR_KEY
+```
+
+### Major Dataset Paths
+
+| Dataset | Path Segment | Description |
+|---------|-------------|-------------|
+| ACS 5-Year Detailed Tables | `acs/acs5` | 5-year estimates, most geographies (2009-present) |
+| ACS 1-Year Detailed Tables | `acs/acs1` | 1-year estimates, areas 65k+ pop (2005-present) |
+| ACS 5-Year Subject Tables | `acs/acs5/subject` | Precomputed subject tables |
+| ACS 5-Year Data Profiles | `acs/acs5/profile` | Social/economic/housing profiles |
+| Decennial Census (2020) | `dec/dhc` | Demographic and Housing Characteristics |
+| Decennial Census (2020 PL) | `dec/pl` | Redistricting data (PL 94-171) |
+| Decennial Census (2010) | `dec/sf1` | Summary File 1 |
+| Population Estimates | `pep/population` | Annual population estimates |
+| Economic Census | `ecnbasic` | Economic Census (2017, 2022) |
+| County Business Patterns | `cbp` | Business establishment counts |
+| Annual Business Survey | `abscs` | Business characteristics |
+
+---
+
+## Key Endpoints
+
+### 1. ACS 5-Year Estimates (Most Common)
+
+```
+GET /data/{year}/acs/acs5?get={variables}&for={geography}&key=YOUR_KEY
+```
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `get`     | Yes      | Comma-separated variable names (e.g., `NAME,B01001_001E`) |
+| `for`     | Yes      | Target geography (e.g., `state:*`, `county:*`, `tract:*`) |
+| `in`      | Sometimes | Parent geography for sub-state levels |
+| `key`     | Yes      | Your API key |
+
+**Example (total population for all states, 2022 ACS 5-year):**
+```
+https://api.census.gov/data/2022/acs/acs5?get=NAME,B01001_001E&for=state:*&key=YOUR_KEY
+```
+
+**Example (median household income for all counties in California):**
+```
+https://api.census.gov/data/2022/acs/acs5?get=NAME,B19013_001E&for=county:*&in=state:06&key=YOUR_KEY
+```
+
+**Example (population by race for a specific tract):**
+```
+https://api.census.gov/data/2022/acs/acs5?get=NAME,B02001_001E,B02001_002E,B02001_003E&for=tract:000100&in=state:06&in=county:075&key=YOUR_KEY
+```
+
+**Response (JSON array of arrays, first row is headers):**
+```json
+[
+  ["NAME", "B01001_001E", "state"],
+  ["Alabama", "5024279", "01"],
+  ["Alaska", "733391", "02"],
+  ["Arizona", "7151502", "04"]
+]
+```
+
+### 2. ACS 1-Year Estimates
+
+```
+GET /data/{year}/acs/acs1?get={variables}&for={geography}&key=YOUR_KEY
+```
+Same parameters as ACS 5-year. Only available for geographies with 65,000+ population.
+
+**Example (poverty rate for all states):**
+```
+https://api.census.gov/data/2022/acs/acs1?get=NAME,B17001_001E,B17001_002E&for=state:*&key=YOUR_KEY
+```
+
+### 3. ACS Data Profiles
+
+```
+GET /data/{year}/acs/acs5/profile?get={variables}&for={geography}&key=YOUR_KEY
+```
+Uses `DP` prefix variables with precomputed percentages.
+
+**Example (educational attainment profile):**
+```
+https://api.census.gov/data/2022/acs/acs5/profile?get=NAME,DP02_0068PE&for=state:*&key=YOUR_KEY
+```
+
+### 4. Decennial Census 2020
+
+```
+GET /data/2020/dec/dhc?get={variables}&for={geography}&key=YOUR_KEY
+```
+
+**Example (total population by state, 2020 Census):**
+```
+https://api.census.gov/data/2020/dec/dhc?get=NAME,P1_001N&for=state:*&key=YOUR_KEY
+```
+
+### 5. Decennial Census 2010
+
+```
+GET /data/2010/dec/sf1?get={variables}&for={geography}&key=YOUR_KEY
+```
+
+**Example:**
+```
+https://api.census.gov/data/2010/dec/sf1?get=NAME,P001001&for=state:*&key=YOUR_KEY
+```
+
+### 6. Discover Available Variables
+
+```
+GET /data/{year}/{dataset}/variables.json
+```
+
+**Example:**
+```
+https://api.census.gov/data/2022/acs/acs5/variables.json
+```
+Returns a large JSON object listing all available variables with labels and concepts.
+
+### 7. Discover Available Geographies
+
+```
+GET /data/{year}/{dataset}/geography.json
+```
+
+**Example:**
+```
+https://api.census.gov/data/2022/acs/acs5/geography.json
+```
+
+### 8. List Available Datasets
+
+```
+GET /data.json
+```
+
+Returns all available datasets with their titles, years, and API endpoints.
+
+---
+
+## Geography Syntax
+
+| Level | `for` syntax | `in` requirement |
+|-------|-------------|-----------------|
+| Nation | `us:1` or `us:*` | None |
+| State | `state:06` or `state:*` | None |
+| County | `county:075` or `county:*` | `in=state:06` (optional for all) |
+| County Subdivision | `county subdivision:*` | `in=state:XX&in=county:YYY` |
+| Census Tract | `tract:*` | `in=state:XX&in=county:YYY` |
+| Block Group | `block group:*` | `in=state:XX&in=county:YYY&in=tract:ZZZZZZ` |
+| Place (city) | `place:*` | `in=state:XX` |
+| Metro Area (CBSA) | `metropolitan statistical area/micropolitan statistical area:*` | None |
+| ZIP Code Tab Area | `zip code tabulation area:*` | None |
+
+State FIPS codes: `01`=AL, `02`=AK, `04`=AZ, `05`=AR, `06`=CA, `08`=CO, `09`=CT, `10`=DE, `11`=DC, `12`=FL, `13`=GA, `15`=HI, `16`=ID, `17`=IL, `18`=IN, `19`=IA, `20`=KS, `21`=KY, `22`=LA, `23`=ME, `24`=MD, `25`=MA, `26`=MI, `27`=MN, `28`=MS, `29`=MO, `30`=MT, `31`=NE, `32`=NV, `33`=NH, `34`=NJ, `35`=NM, `36`=NY, `37`=NC, `38`=ND, `39`=OH, `40`=OK, `41`=OR, `42`=PA, `44`=RI, `45`=SC, `46`=SD, `47`=TN, `48`=TX, `49`=UT, `50`=VT, `51`=VA, `53`=WA, `54`=WV, `55`=WI, `56`=WY
+
+---
+
+## Common Variable Codes
+
+### ACS Detailed Tables (B-tables)
+| Variable | Description |
+|----------|-------------|
+| `B01001_001E` | Total population |
+| `B01002_001E` | Median age |
+| `B02001_001E` | Total (race) |
+| `B02001_002E` | White alone |
+| `B02001_003E` | Black or African American alone |
+| `B03001_003E` | Hispanic or Latino |
+| `B19013_001E` | Median household income |
+| `B19001_001E` | Household income (total, for distribution) |
+| `B25077_001E` | Median home value |
+| `B25064_001E` | Median gross rent |
+| `B17001_001E` | Poverty status (total) |
+| `B17001_002E` | Poverty status (below poverty) |
+| `B15003_022E` | Bachelor's degree |
+| `B15003_023E` | Master's degree |
+| `B15003_025E` | Doctorate degree |
+| `B23025_005E` | Unemployed (civilian labor force) |
+| `B25001_001E` | Total housing units |
+| `B08301_001E` | Means of transportation to work (total) |
+
+Variable naming: `B{table}_{seq}E` for estimates, `B{table}_{seq}M` for margins of error.
+
+### ACS Data Profile Variables (DP-tables)
+| Variable | Description |
+|----------|-------------|
+| `DP02_0068PE` | % with bachelor's degree or higher |
+| `DP03_0062E` | Median household income |
+| `DP03_0128PE` | % below poverty level |
+| `DP04_0089E` | Median home value |
+| `DP05_0001E` | Total population |
+
+### Decennial 2020 (DHC)
+| Variable | Description |
+|----------|-------------|
+| `P1_001N` | Total population |
+| `P1_003N` | White alone |
+| `P1_004N` | Black or African American alone |
+| `H1_001N` | Total housing units |
+| `H1_002N` | Occupied housing units |
+
+---
+
+## Response Format
+All data responses are **JSON arrays of arrays**. The first array is always the column headers; subsequent arrays are data rows.
+
+```json
+[
+  ["NAME", "B01001_001E", "B19013_001E", "state", "county"],
+  ["Los Angeles County, California", "10014009", "73538", "06", "037"],
+  ["San Diego County, California", "3298634", "85750", "06", "073"]
+]
+```
+
+- Values are strings (even numeric ones).
+- Missing or unavailable data may appear as `null`, `"-"`, or `"N"`.
+- Annotation values: `"-"` (too few sample cases), `"N"` (not available), `"(X)"` (not applicable).
+
+## Notes
+- Always include `NAME` in your `get` parameter to get human-readable geography labels.
+- The `E` suffix means "Estimate"; use `M` suffix for Margin of Error (e.g., `B19013_001M`).
+- Variable discovery: browse https://api.census.gov/data/{year}/acs/acs5/variables.html for a searchable table.
+- For ACS, 5-year estimates cover all geographies but are less current; 1-year covers only larger geographies but is more recent.
+- Group endpoint: `?get=group(B01001)` retrieves all variables in a table group.

package/skills/scientific/database-lookup/references/chebi.md

@@ -0,0 +1,103 @@
+# ChEBI (Chemical Entities of Biological Interest) API Reference
+
+## Base URLs
+- **OLS (Ontology Lookup Service) API**: `https://www.ebi.ac.uk/ols4/api`
+- **ChEBI Web Services (SOAP)**: `https://www.ebi.ac.uk/webservices/chebi/2.0/test` (SOAP/XML only)
+- **ChEBI LibChebi REST (limited)**: entity pages at `https://www.ebi.ac.uk/chebi`
+
+## Authentication
+None required. All endpoints are public.
+
+## Rate Limits
+No published hard limits. EBI general guidance: reasonable usage.
+
+## Important Note
+ChEBI's primary web service is **SOAP-based** (XML), not REST. For REST-style JSON access, use the **EBI OLS4 API** which indexes ChEBI as an ontology.
+
+---
+
+## OLS4 API Endpoints (Recommended for REST/JSON)
+
+### 1. Search ChEBI Terms
+```
+GET https://www.ebi.ac.uk/ols4/api/search?q={query}&ontology=chebi
+```
+Example:
+```
+GET https://www.ebi.ac.uk/ols4/api/search?q=aspirin&ontology=chebi
+```
+Returns JSON with matching ChEBI terms, IDs, definitions, synonyms.
+
+### 2. Lookup by ChEBI ID
+```
+GET https://www.ebi.ac.uk/ols4/api/ontologies/chebi/terms?iri=http://purl.obolibrary.org/obo/CHEBI_{id}
+```
+Example:
+```
+GET https://www.ebi.ac.uk/ols4/api/ontologies/chebi/terms?iri=http://purl.obolibrary.org/obo/CHEBI_15365
+```
+Returns full term details: name, definition, synonyms, xrefs, relationships.
+
+### 3. Get Term by Short Form
+```
+GET https://www.ebi.ac.uk/ols4/api/ontologies/chebi/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FCHEBI_{id}
+```
+(Double-encoded IRI in path.)
+
+### 4. Term Hierarchy — Parents
+```
+GET https://www.ebi.ac.uk/ols4/api/ontologies/chebi/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FCHEBI_{id}/parents
+```
+
+### 5. Term Hierarchy — Children
+```
+GET https://www.ebi.ac.uk/ols4/api/ontologies/chebi/terms/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FCHEBI_{id}/children
+```
+
+### 6. Ontology Metadata
+```
+GET https://www.ebi.ac.uk/ols4/api/ontologies/chebi
+```
+
+## OLS Search Response Format
+```json
+{
+  "response": {
+    "numFound": 5,
+    "docs": [
+      {
+        "id": "chebi:15365",
+        "iri": "http://purl.obolibrary.org/obo/CHEBI_15365",
+        "label": "aspirin",
+        "description": ["A member of the class of benzoic acids..."],
+        "short_form": "CHEBI_15365",
+        "obo_id": "CHEBI:15365",
+        "ontology_name": "chebi",
+        "type": "class"
+      }
+    ]
+  }
+}
+```
+
+## ChEBI SOAP Web Service (Alternative)
+If you need chemical-specific data (formula, mass, structure, InChI), use the SOAP service:
+- WSDL: `https://www.ebi.ac.uk/webservices/chebi/2.0/webservice?wsdl`
+- Operations: `getCompleteEntity`, `getLiteEntity`, `getStructureSearch`, `getOntologyChildren`, `getOntologyParents`
+- Returns XML only.
+
+Example SOAP request for `getCompleteEntity`:
+```xml
+<soapenv:Body>
+  <chebi:getCompleteEntity>
+    <chebi:chebiId>CHEBI:15365</chebi:chebiId>
+  </chebi:getCompleteEntity>
+</soapenv:Body>
+```
+Returns: formula, mass, charge, InChI, InChIKey, SMILES, synonyms, database links, ontology parents/children.
+
+## Notes
+- For programmatic REST access, OLS4 is the easiest path.
+- For chemical structure searches (by InChI, SMILES, substructure), the SOAP service is required.
+- ChEBI IDs are numeric (e.g., 15365) but referenced as "CHEBI:15365" in OBO format.
+- PubChem and UniChem can cross-reference ChEBI IDs to other chemical databases.

package/skills/scientific/database-lookup/references/chembl.md

@@ -0,0 +1,80 @@
+# ChEMBL REST API
+
+## Base URL
+```
+https://www.ebi.ac.uk/chembl/api/data
+```
+
+## Auth
+No API key required. Fully open and free.
+
+## Key Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `/molecule/{chembl_id}` | Get molecule by ChEMBL ID |
+| `/molecule/search?q={query}` | Free-text molecule search |
+| `/target/{chembl_id}` | Get target by ChEMBL ID |
+| `/target/search?q={query}` | Free-text target search |
+| `/activity?molecule_chembl_id={id}` | Activities for a molecule |
+| `/activity?target_chembl_id={id}` | Activities for a target |
+| `/mechanism?molecule_chembl_id={id}` | Mechanism of action |
+| `/drug_indication?molecule_chembl_id={id}` | Drug indications |
+| `/similarity/{smiles}/{threshold}` | Similarity search (threshold 40-100) |
+| `/substructure/{smiles}` | Substructure search |
+
+## Common Parameters
+
+- `format=json` — response format (default json)
+- `limit` — results per page (default 20, max 1000)
+- `offset` — pagination offset
+- `order_by` — sort field (prefix `-` for descending)
+- `only` — return only specified fields (comma-separated)
+
+### Filtering operators (append to field names)
+`__exact`, `__icontains`, `__gt`, `__gte`, `__lt`, `__lte`, `__in`, `__isnull`, `__startswith`, `__range`, `__regex`
+
+## Example Calls
+
+```
+# Get molecule by ID
+/molecule/CHEMBL25.json
+
+# Search molecules by name
+/molecule/search?q=aspirin&format=json
+
+# Activities for a target with potency filter
+/activity?target_chembl_id=CHEMBL240&pchembl_value__gte=6&format=json&limit=100
+
+# Similarity search (80% threshold)
+/similarity/CC(%3DO)Oc1ccccc1C(%3DO)O/80.json
+
+# Approved drugs only
+/molecule?max_phase=4&format=json
+
+# Mechanism of action
+/mechanism?molecule_chembl_id=CHEMBL25&format=json
+```
+
+## Response Format (molecule)
+```json
+{
+  "page_meta": {"limit": 20, "offset": 0, "total_count": 150},
+  "molecules": [{
+    "molecule_chembl_id": "CHEMBL25",
+    "pref_name": "ASPIRIN",
+    "max_phase": 4,
+    "molecule_properties": {
+      "full_mwt": 180.16, "full_molformula": "C9H8O4",
+      "alogp": 1.31, "hba": 3, "hbd": 1, "psa": 63.60
+    },
+    "molecule_structures": {
+      "canonical_smiles": "CC(=O)Oc1ccccc1C(=O)O",
+      "standard_inchi_key": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N"
+    }
+  }]
+}
+```
+
+## Rate Limits
+No strict limit. Keep under ~10 req/sec. No auth required.