# Agent Commerce Store — Full API Schemas
base_url: https://agent-commerce.store
l402_proxy_base: https://api.lightningenable.com/l402/proxy
status: early_access
payments: non_refundable
idempotency_header: X-Idempotency-Key (optional, prevents duplicate invoices on rapid/retried requests; same key within 5 min returns same 402 challenge)

## Envelope
All /api/* responses wrapped:
{"status":"ok|error","data":{...},"meta":{"token_estimate":int,"price_sats":int,"cached":bool,"timestamp":"ISO8601","path":"string","l402_url":"string|null","test_free_url":"string|null"}}
meta.l402_url: the L402 paid endpoint URL for this same request (pay via Lightning to access the premium version)
meta.test_free_url: the free test URL for this endpoint (use to validate parameters before paying)

===

## Weather Intel | proxy_id: weather-intel-e0cf
source: NWS | region: US | note: transient 404s auto-retried 3x

### GET /api/weather/forecast | 3 sats
params:
  latitude: {type: double, required: true, range: [-90, 90], format: "decimal degrees"}
  longitude: {type: double, required: true, range: [-180, 180], format: "decimal degrees"}
example: /api/weather/forecast?latitude=40.7128&longitude=-74.0060
response:
{
  "latitude": 40.71,
  "longitude": -74.0,
  "location": "New York, NY",
  "timezone": "America/New_York",
  "generatedAt": "2025-01-15T12:00:00Z",
  "periods": [
    {
      "name": "Today",
      "startTime": "2025-01-15T06:00:00-05:00",
      "endTime": "2025-01-15T18:00:00-05:00",
      "temperature": 45,
      "temperatureUnit": "F",
      "windSpeed": "10 mph",
      "windDirection": "NW",
      "shortForecast": "Partly Cloudy",
      "detailedForecast": "Partly cloudy, with a high near 45.",
      "isDaytime": true,
      "precipitationProbability": 10,
      "outdoorSuitable": true,
      "outdoorReason": "Good conditions for outdoor activities"
    }
  ]
}

### GET /api/weather/alerts | 2 sats
params:
  state: {type: string, required: true, format: "2-letter US state code", enum: [AL,AK,AZ,AR,CA,CO,CT,DE,FL,GA,HI,ID,IL,IN,IA,KS,KY,LA,ME,MD,MA,MI,MN,MS,MO,MT,NE,NV,NH,NJ,NM,NY,NC,ND,OH,OK,OR,PA,RI,SC,SD,TN,TX,UT,VT,VA,WA,WV,WI,WY]}
example: /api/weather/alerts?state=TX
response:
{
  "state": "TX",
  "generatedAt": "2025-01-15T12:00:00Z",
  "totalAlerts": 2,
  "alerts": [
    {
      "id": "urn:oid:2.49.0.1.840.0...",
      "event": "Winter Storm Warning",
      "severity": "Severe",
      "severityScore": 80,
      "urgency": "Expected",
      "certainty": "Likely",
      "headline": "Winter Storm Warning issued...",
      "description": "Heavy snow expected...",
      "areaDescription": "Northern Texas",
      "onset": "2025-01-15T18:00:00Z",
      "expires": "2025-01-16T12:00:00Z"
    }
  ]
}

### GET /api/weather/conditions | 2 sats
params:
  latitude: {type: double, required: true, range: [-90, 90]}
  longitude: {type: double, required: true, range: [-180, 180]}
example: /api/weather/conditions?latitude=40.7128&longitude=-74.0060
response:
{
  "latitude": 40.71,
  "longitude": -74.0,
  "station": "KNYC",
  "observedAt": "2025-01-15T11:51:00Z",
  "generatedAt": "2025-01-15T12:00:00Z",
  "conditions": {
    "description": "Partly Cloudy",
    "temperatureF": 44.1,
    "temperatureC": 6.7,
    "dewpointF": 30.2,
    "dewpointC": -1.0,
    "relativeHumidity": 55,
    "windSpeed": "12 mph",
    "windDirection": "NW",
    "barometricPressurePa": 101320,
    "visibilityMeters": 16093,
    "windChillF": 38.5,
    "heatIndexF": null
  }
}

===

## Smart Wikipedia | proxy_id: smart-wikipedia-aaec
source: Wikipedia + Wikidata | region: global | note: param is "topic" not "query"; use exact article titles

### GET /api/wikipedia/summary | 2 sats
params:
  topic: {type: string, required: true, description: "Wikipedia article title", examples: ["Bitcoin", "Albert Einstein", "Lightning Network"]}
example: /api/wikipedia/summary?topic=Bitcoin
response:
{
  "topic": "Bitcoin",
  "title": "Bitcoin",
  "summary": "Cryptocurrency",
  "extract": "Bitcoin is a cryptocurrency...",
  "keyFacts": ["Bitcoin is a cryptocurrency invented in 2008.", "It was created by Satoshi Nakamoto."],
  "thumbnailUrl": "https://upload.wikimedia.org/...",
  "wikipediaUrl": "https://en.wikipedia.org/wiki/Bitcoin",
  "isDisambiguation": false,
  "hasControversy": false,
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/wikipedia/entity | 3 sats
params:
  topic: {type: string, required: true, description: "topic to find Wikidata entity"}
example: /api/wikipedia/entity?topic=Satoshi+Nakamoto
response:
{
  "topic": "Satoshi Nakamoto",
  "wikidataId": "Q489349",
  "label": "Satoshi Nakamoto",
  "description": "creator of Bitcoin",
  "properties": {
    "instance_of": "Q5",
    "occupation": "cryptographer"
  },
  "aliases": ["Satoshi"],
  "wikipediaUrl": "https://en.wikipedia.org/wiki/Satoshi_Nakamoto",
  "wikidataUrl": "https://www.wikidata.org/wiki/Q489349",
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/wikipedia/related | 2 sats
params:
  topic: {type: string, required: true}
example: /api/wikipedia/related?topic=Lightning+Network
response:
{
  "topic": "Lightning Network",
  "related": [
    {
      "title": "Bitcoin",
      "description": null,
      "wikipediaUrl": "https://en.wikipedia.org/wiki/Bitcoin"
    }
  ],
  "seeAlso": [],
  "categories": ["Payment systems", "Bitcoin"],
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## Paper Scout | proxy_id: paper-scout-247e
source: arXiv | region: global

### GET /api/papers/search | 3 sats
params:
  query: {type: string, required: true}
  start: {type: int, required: false, default: 0}
  maxResults: {type: int, required: false, default: 10, max: 50}
example: /api/papers/search?query=transformer+attention&maxResults=5
response:
{
  "query": "transformer attention",
  "totalResults": 15000,
  "startIndex": 0,
  "itemsPerPage": 10,
  "papers": [
    {
      "arxivId": "1706.03762",
      "title": "Attention Is All You Need",
      "summary": "The dominant sequence transduction models...",
      "authors": ["Ashish Vaswani", "Noam Shazeer"],
      "published": "2017-06-12T00:00:00Z",
      "updated": "2017-06-12T00:00:00Z",
      "categories": ["cs.CL", "cs.LG"],
      "primaryCategory": "cs.CL",
      "doiUrl": null,
      "pdfUrl": "https://arxiv.org/pdf/1706.03762",
      "abstractUrl": "https://arxiv.org/abs/1706.03762",
      "comment": "15 pages, 5 figures"
    }
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/papers/{arxivId} | 3 sats
params:
  arxivId: {type: string, required: true, format: "arXiv ID", examples: ["1706.03762", "2301.00001"]}
example: /api/papers/1706.03762
response: same as search result item + journalRef:string|null

===

## Census Query | proxy_id: census-query-2a22
source: US Census Bureau | region: US | note: use "City, State" format; full state names preferred over abbreviations

### GET /api/census/population | 3 sats
params:
  place: {type: string, required: true, format: "City, State", examples: ["Houston, Texas", "Austin, TX", "New York, New York"]}
example: /api/census/population?place=Houston%2C+Texas
response:
{
  "place": "Austin, TX",
  "resolvedName": "Austin city, Texas",
  "fipsCode": "05000",
  "state": "TX",
  "population": 979882,
  "source": "U.S. Census Bureau, American Community Survey 5-Year Estimates",
  "dataYear": "2022",
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/census/demographics | 5 sats
params:
  place: {type: string, required: true, format: "City, State"}
example: /api/census/demographics?place=Austin%2C+Texas
response:
{
  "place": "Austin, TX",
  "resolvedName": "Austin city, Texas",
  "fipsCode": "05000",
  "state": "TX",
  "totalPopulation": 979882,
  "age": {"under18": 210000, "age18To64": 650000, "age65Plus": 119882, "medianAge": 34.5},
  "race": {"white": 550000, "blackOrAfricanAmerican": 75000, "asian": 85000, "hispanicOrLatino": 330000},
  "housing": {"totalHousingUnits": 420000, "occupiedUnits": 390000, "vacantUnits": 30000, "medianHomeValue": 375000, "medianRent": 1350},
  "source": "U.S. Census Bureau, American Community Survey 5-Year Estimates",
  "dataYear": "2022",
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## SEC EDGAR | proxy_id: sec-edgar-38a5
source: SEC EDGAR | region: US | note: CIK is numeric, auto-padded; accession format 0000320193-24-000123

### GET /api/edgar/search | 8 sats
params:
  query: {type: string, required: true, description: "company name, ticker, or filing text"}
  dateRange: {type: string, required: false}
  form: {type: string, required: false, examples: ["10-K", "10-Q", "8-K", "S-1", "DEF 14A", "4"]}
example: /api/edgar/search?query=Tesla&form=10-K
response:
{
  "query": "Tesla annual report",
  "totalResults": 245,
  "filings": [
    {
      "accessionNumber": "0001628280-24-002390",
      "formType": "10-K",
      "formTypeDescription": "Annual report",
      "companyName": "Tesla, Inc.",
      "cik": "0001318605",
      "filedDate": "2024-01-29",
      "reportDate": "2023-12-31",
      "documentUrl": "https://www.sec.gov/Archives/edgar/data/1318605/..."
    }
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/edgar/company/{cik} | 10 sats
params:
  cik: {type: string, required: true, description: "CIK number, auto-padded to 10 digits", examples: ["320193", "1318605"]}
example: /api/edgar/company/320193
response:
{
  "cik": "0001318605",
  "companyName": "Tesla, Inc.",
  "keyFacts": [
    {"label": "Revenue", "value": 96773000000, "unit": "USD", "period": "2023"}
  ],
  "recentFilings": [
    {"accessionNumber": "0001628280-24-002390", "formType": "10-K", "formTypeDescription": "Annual report", "filedDate": "2024-01-29", "reportDate": "2023-12-31"}
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/edgar/filing/{accessionNumber} | 10 sats
params:
  accessionNumber: {type: string, required: true, format: "0000320193-24-000123"}
example: /api/edgar/filing/0001628280-24-002390
response:
{
  "accessionNumber": "0001628280-24-002390",
  "formType": "10-K",
  "formTypeDescription": "Annual report",
  "companyName": "Tesla, Inc.",
  "cik": "0001318605",
  "filedDate": "2024-01-29",
  "reportDate": "2023-12-31",
  "documentUrl": "https://www.sec.gov/Archives/edgar/data/1318605/...",
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## OpenFDA Drug Safety | proxy_id: openfda-drug-safety-781f
source: openFDA | region: US

### GET /api/openfda/adverse-events | 5 sats
params:
  drug: {type: string, required: true, examples: ["aspirin", "ibuprofen", "metformin"]}
  limit: {type: int, required: false, default: 10}
example: /api/openfda/adverse-events?drug=aspirin&limit=5
response:
{
  "drug": "aspirin",
  "totalResults": 84532,
  "reports": [
    {
      "receiveDate": "2024-03-15",
      "seriousness": "Serious",
      "severityScore": 75,
      "patient": {"age": 65, "sex": "Female", "weight": "70 kg"},
      "reactions": ["Gastrointestinal haemorrhage", "Nausea"],
      "outcomes": ["Hospitalization"]
    }
  ],
  "reactionSummary": {
    "topReactions": [
      {"reaction": "Nausea", "count": 12450},
      {"reaction": "Headache", "count": 8320}
    ]
  },
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/openfda/recalls | 5 sats
params:
  query: {type: string, required: true}
  limit: {type: int, required: false, default: 10}
example: /api/openfda/recalls?query=insulin+pump
response:
{
  "query": "insulin pump",
  "totalResults": 156,
  "recalls": [
    {
      "recallNumber": "Z-1234-2024",
      "classification": "Class I",
      "status": "Ongoing",
      "reason": "Device may deliver incorrect insulin dose",
      "description": "Insulin pump model XYZ with firmware version 2.1",
      "recallingFirm": "Medical Devices Corp.",
      "recallInitiationDate": "2024-06-15",
      "productDescription": "Insulin infusion pump",
      "voluntaryMandated": "Voluntary: Firm initiated"
    }
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/openfda/labels | 5 sats
params:
  drug: {type: string, required: true}
example: /api/openfda/labels?drug=ibuprofen
response:
{
  "drug": "ibuprofen",
  "brandName": "Advil",
  "genericName": "Ibuprofen",
  "manufacturer": "Pfizer Consumer Healthcare",
  "indications": "For the temporary relief of minor aches and pains...",
  "warnings": "Allergy alert: Ibuprofen may cause a severe allergic reaction...",
  "dosage": "Adults and children 12 years and over: take 1 tablet every 4 to 6 hours...",
  "contraindications": "Do not use if you have ever had an allergic reaction...",
  "adverseReactions": "Nausea, vomiting, dizziness, headache...",
  "drugInteractions": "Aspirin, blood thinners, corticosteroids, SSRIs...",
  "activeIngredients": ["Ibuprofen 200mg"],
  "route": "Oral",
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## PubMed Biomedical | proxy_id: pubmed-biomedical-bc1e
source: NCBI PubMed | region: global

### GET /api/pubmed/search | 6 sats
params:
  query: {type: string, required: true}
  limit: {type: int, required: false, default: 10, max: 50}
example: /api/pubmed/search?query=CRISPR+gene+therapy&limit=5
response:
{
  "query": "CRISPR gene therapy",
  "totalResults": 28450,
  "articles": [
    {
      "pmid": "38123456",
      "title": "CRISPR-Cas9 Gene Editing for Sickle Cell Disease",
      "abstract": "Background: Sickle cell disease affects millions worldwide...",
      "structuredAbstract": [
        {"label": "Background", "text": "Sickle cell disease affects millions worldwide..."},
        {"label": "Methods", "text": "We conducted a phase 1/2 clinical trial..."},
        {"label": "Results", "text": "All 12 patients showed sustained improvement..."},
        {"label": "Conclusions", "text": "CRISPR-based gene editing shows promise..."}
      ],
      "authors": ["Smith J", "Johnson A", "Williams B"],
      "journal": "New England Journal of Medicine",
      "publishedDate": "2024-03-15",
      "doi": "10.1056/NEJMoa2312345",
      "meshTerms": ["CRISPR-Cas Systems", "Gene Editing", "Anemia, Sickle Cell"]
    }
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/pubmed/{pmid} | 7 sats
params:
  pmid: {type: string, required: true, examples: ["38123456"]}
example: /api/pubmed/38123456
response:
{
  "pmid": "38123456",
  "title": "CRISPR-Cas9 Gene Editing for Sickle Cell Disease",
  "abstract": "Background: Sickle cell disease affects millions worldwide...",
  "structuredAbstract": [
    {"label": "Background", "text": "Sickle cell disease affects millions worldwide..."},
    {"label": "Methods", "text": "We conducted a phase 1/2 clinical trial..."},
    {"label": "Results", "text": "All 12 patients showed sustained improvement..."},
    {"label": "Conclusions", "text": "CRISPR-based gene editing shows promise..."}
  ],
  "authors": ["Smith J", "Johnson A", "Williams B"],
  "journal": "New England Journal of Medicine",
  "volume": "390",
  "issue": "12",
  "pages": "1085-1097",
  "publishedDate": "2024-03-15",
  "doi": "10.1056/NEJMoa2312345",
  "meshTerms": ["CRISPR-Cas Systems", "Gene Editing", "Anemia, Sickle Cell"],
  "keywords": ["CRISPR", "gene therapy", "sickle cell", "hemoglobin"],
  "publicationTypes": ["Journal Article", "Clinical Trial"],
  "fullTextUrl": "https://doi.org/10.1056/NEJMoa2312345",
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## FRED Economic Data | proxy_id: fred-economic-data-bf5f
source: Federal Reserve Bank of St. Louis | region: US/global | note: common series IDs: GDP, UNRATE, CPIAUCSL, DFF, SP500, FEDFUNDS

### GET /api/fred/search | 4 sats
params:
  query: {type: string, required: true}
  limit: {type: int, required: false, default: 10}
example: /api/fred/search?query=unemployment+rate
response:
{
  "query": "unemployment rate",
  "totalResults": 1245,
  "series": [
    {
      "seriesId": "UNRATE",
      "title": "Unemployment Rate",
      "frequency": "Monthly",
      "units": "Percent",
      "seasonalAdjustment": "Seasonally Adjusted",
      "lastUpdated": "2024-12-06",
      "observationStart": "1948-01-01",
      "observationEnd": "2024-11-01",
      "popularity": 95,
      "notes": "The unemployment rate represents the number of unemployed as a percentage of the labor force."
    }
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/fred/series/{seriesId} | 5 sats
params:
  seriesId: {type: string, required: true, examples: ["UNRATE", "GDP", "CPIAUCSL", "DFF", "SP500"]}
example: /api/fred/series/UNRATE
response:
{
  "seriesId": "UNRATE",
  "title": "Unemployment Rate",
  "frequency": "Monthly",
  "units": "Percent",
  "seasonalAdjustment": "Seasonally Adjusted",
  "lastUpdated": "2024-12-06",
  "observations": [
    {"date": "2024-09-01", "value": 4.1},
    {"date": "2024-10-01", "value": 4.1},
    {"date": "2024-11-01", "value": 4.2}
  ],
  "stats": {"min": 3.4, "max": 4.2, "avg": 3.8, "latestChange": 0.1},
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/fred/series/{seriesId}/data | 5 sats
params:
  seriesId: {type: string, required: true}
  start: {type: string, required: false, format: "YYYY-MM-DD"}
  end: {type: string, required: false, format: "YYYY-MM-DD"}
example: /api/fred/series/UNRATE/data?start=2023-01-01&end=2024-12-31
response:
{
  "seriesId": "UNRATE",
  "title": "Unemployment Rate",
  "frequency": "Monthly",
  "units": "Percent",
  "startDate": "2023-01-01",
  "endDate": "2024-11-01",
  "observations": [
    {"date": "2023-01-01", "value": 3.4},
    {"date": "2023-02-01", "value": 3.6},
    {"date": "2023-03-01", "value": 3.5}
  ],
  "stats": {"min": 3.4, "max": 4.2, "avg": 3.8, "latestChange": 0.1},
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## OpenAlex Scholarly | proxy_id: openalex-scholarly-c9ff
source: OpenAlex (CC0) | region: global

### GET /api/openalex/search | 3 sats
params:
  query: {type: string, required: true}
  limit: {type: int, required: false, default: 10, max: 50}
example: /api/openalex/search?query=machine+learning+healthcare
response:
{
  "query": "machine learning healthcare",
  "totalResults": 185420,
  "works": [
    {
      "id": "W2741809807",
      "title": "Deep Learning for Health Informatics",
      "abstract": "The amount of health data collected is growing rapidly...",
      "authors": [
        {"name": "Daniele Ravì", "institution": "Imperial College London"}
      ],
      "publicationYear": 2017,
      "citedByCount": 2845,
      "isOpenAccess": true,
      "pdfUrl": "https://europepmc.org/articles/PMC5820467?pdf=render",
      "journal": "IEEE Journal of Biomedical and Health Informatics",
      "doi": "10.1109/JBHI.2016.2636665"
    }
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/openalex/work/{id} | 5 sats
params:
  id: {type: string, required: true, description: "OpenAlex work ID or DOI", examples: ["W2741809807", "10.1109/JBHI.2016.2636665"]}
example: /api/openalex/work/W2741809807
response:
{
  "id": "W2741809807",
  "title": "Deep Learning for Health Informatics",
  "abstract": "The amount of health data collected is growing rapidly...",
  "authors": [
    {"name": "Daniele Ravì", "institution": "Imperial College London", "orcid": "0000-0002-1234-5678"}
  ],
  "publicationYear": 2017,
  "citedByCount": 2845,
  "isOpenAccess": true,
  "pdfUrl": "https://europepmc.org/articles/PMC5820467?pdf=render",
  "journal": "IEEE Journal of Biomedical and Health Informatics",
  "doi": "10.1109/JBHI.2016.2636665",
  "volume": "21",
  "issue": "1",
  "pages": "4-21",
  "topics": [
    {"name": "Deep Learning", "score": 0.95},
    {"name": "Health Informatics", "score": 0.88}
  ],
  "referencedWorksCount": 142,
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/openalex/author/{id} | 3 sats
params:
  id: {type: string, required: true, examples: ["A5023888391"]}
example: /api/openalex/author/A5023888391
response:
{
  "id": "A5023888391",
  "displayName": "Geoffrey Hinton",
  "orcid": "0000-0002-1234-5678",
  "worksCount": 524,
  "citedByCount": 584210,
  "hIndex": 172,
  "topics": [
    {"name": "Deep Learning", "count": 215},
    {"name": "Neural Networks", "count": 198}
  ],
  "institution": {"name": "University of Toronto", "country": "Canada", "type": "education"},
  "summaryStats": {"worksCount": 524, "citedByCount": 584210, "hIndex": 172, "i10Index": 312},
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## Crossref DOI | proxy_id: crossref-doi-ecfd
source: Crossref | region: global

### GET /api/crossref/search | 2 sats
params:
  query: {type: string, required: true}
  limit: {type: int, required: false, default: 10}
example: /api/crossref/search?query=climate+change+agriculture
response:
{
  "query": "climate change impact agriculture",
  "totalResults": 98450,
  "works": [
    {
      "doi": "10.1038/nature12373",
      "title": "Increasing drought under global warming in observations and models",
      "authors": [
        {"given": "Aiguo", "family": "Dai", "affiliation": "University at Albany"}
      ],
      "publishedDate": "2013-01-01",
      "journal": "Nature Climate Change",
      "citation": "Dai, A. (2013). Increasing drought under global warming in observations and models. Nature Climate Change, 3(1), 52-58.",
      "isOpenAccess": false,
      "licenseUrl": null,
      "type": "journal-article",
      "publisher": "Springer Nature"
    }
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/crossref/doi/{doi} | 2 sats
params:
  doi: {type: string, required: true, format: "DOI with slashes", examples: ["10.1038/nature12373", "10.1056/NEJMoa2312345"]}
example: /api/crossref/doi/10.1038/nature12373
response:
{
  "doi": "10.1038/nature12373",
  "title": "Increasing drought under global warming in observations and models",
  "authors": [
    {"given": "Aiguo", "family": "Dai", "affiliation": "University at Albany"}
  ],
  "publishedDate": "2013-01-01",
  "journal": "Nature Climate Change",
  "publisher": "Springer Nature",
  "citation": "Dai, A. (2013). Increasing drought under global warming in observations and models. Nature Climate Change, 3(1), 52-58.",
  "isOpenAccess": false,
  "licenseUrl": null,
  "volume": "3",
  "issue": "1",
  "page": "52-58",
  "type": "journal-article",
  "referencesCount": 85,
  "citedByCount": 4230,
  "issn": ["1758-678X", "1758-6798"],
  "url": "https://doi.org/10.1038/nature12373",
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## Federal Register [DISABLED — upstream blocks cloud IPs]
proxy_id: federal-register-5297
source: Federal Register | region: US | status: temporarily_unavailable

### GET /api/federalregister/search | 3 sats [DISABLED]
params:
  query: {type: string, required: true}
  type: {type: string, required: false, enum: ["rule", "proposed_rule", "notice", "presidential_document"]}
  limit: {type: int, required: false, default: 10}

### GET /api/federalregister/document/{number} | 5 sats [DISABLED]
params:
  number: {type: string, required: true, description: "Federal Register document number"}

### GET /api/federalregister/recent | 3 sats [DISABLED]
params:
  agencies: {type: string, required: false, format: "comma-separated agency slugs"}
  type: {type: string, required: false, enum: ["rule", "proposed_rule", "notice", "presidential_document"]}

===

## Currency Exchange | proxy_id: currency-exchange-9b9c
source: ECB via Frankfurter | region: global | update_frequency: daily ~16:00 CET | currencies: ~33

### GET /api/currency/latest | 1 sat
params:
  base: {type: string, required: false, default: "USD", format: "ISO 4217"}
  symbols: {type: string, required: false, format: "comma-separated ISO 4217 codes", examples: ["EUR,GBP,JPY"]}
example: /api/currency/latest?base=USD&symbols=EUR,GBP,JPY
response:
{
  "base": "USD",
  "date": "2025-01-15",
  "rates": [
    {"code": "EUR", "name": "Euro", "rate": 0.9215, "inverseRate": 1.0852},
    {"code": "GBP", "name": "British Pound", "rate": 0.7842, "inverseRate": 1.2752},
    {"code": "JPY", "name": "Japanese Yen", "rate": 156.32, "inverseRate": 0.0064}
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/currency/convert | 1 sat
params:
  from: {type: string, required: true, format: "ISO 4217"}
  to: {type: string, required: true, format: "ISO 4217"}
  amount: {type: decimal, required: false, default: 1}
example: /api/currency/convert?from=USD&to=EUR&amount=100
response:
{
  "from": "USD",
  "to": "EUR",
  "amount": 100.00,
  "convertedAmount": 92.15,
  "rate": 0.9215,
  "inverseRate": 1.0852,
  "fromName": "United States Dollar",
  "toName": "Euro",
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/currency/historical | 2 sats
params:
  base: {type: string, required: true, format: "ISO 4217"}
  start: {type: string, required: true, format: "YYYY-MM-DD"}
  end: {type: string, required: true, format: "YYYY-MM-DD"}
example: /api/currency/historical?base=USD&start=2024-01-01&end=2024-12-31
response:
{
  "base": "USD",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "rates": [
    {"date": "2024-01-01", "rates": [{"code": "EUR", "rate": 0.9050}, {"code": "GBP", "rate": 0.7865}]},
    {"date": "2024-01-02", "rates": [{"code": "EUR", "rate": 0.9065}, {"code": "GBP", "rate": 0.7870}]}
  ],
  "summary": {"percentageChange": 1.82, "min": 0.9010, "max": 0.9350, "avg": 0.9180},
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## Air Quality Index | proxy_id: air-quality-index-e42f
source: EPA AirNow | region: US | update_frequency: hourly

### GET /api/airquality/current | 2 sats
params:
  latitude: {type: double, required: true, range: [-90, 90]}
  longitude: {type: double, required: true, range: [-180, 180]}
example: /api/airquality/current?latitude=40.7128&longitude=-74.0060
response:
{
  "latitude": 40.71,
  "longitude": -74.0,
  "observations": [
    {
      "pollutant": "PM2.5",
      "aqi": 42,
      "category": "Good",
      "color": "#00E400",
      "healthRecommendation": "Air quality is satisfactory, and air pollution poses little or no risk.",
      "sensitiveGroupWarning": null
    },
    {
      "pollutant": "O3",
      "aqi": 55,
      "category": "Moderate",
      "color": "#FFFF00",
      "healthRecommendation": "Air quality is acceptable. However, there may be a risk for some people.",
      "sensitiveGroupWarning": "Unusually sensitive people should consider reducing prolonged outdoor exertion."
    }
  ],
  "summary": {"overallAqi": 55, "category": "Moderate", "dominantPollutant": "O3"},
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/airquality/forecast | 2 sats
params:
  latitude: {type: double, required: true, range: [-90, 90]}
  longitude: {type: double, required: true, range: [-180, 180]}
example: /api/airquality/forecast?latitude=40.7128&longitude=-74.0060
response:
{
  "latitude": 40.71,
  "longitude": -74.0,
  "forecastDays": [
    {
      "date": "2025-01-16",
      "forecasts": [
        {"pollutant": "PM2.5", "aqi": 38, "category": "Good", "color": "#00E400"},
        {"pollutant": "O3", "aqi": 62, "category": "Moderate", "color": "#FFFF00"}
      ],
      "worstAqi": 62,
      "worstCategory": "Moderate"
    }
  ],
  "worstDay": {"date": "2025-01-17", "aqi": 85, "pollutant": "PM2.5"},
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## Nutrition Facts | proxy_id: nutrition-facts-f147
source: USDA FoodData Central | region: US food database

### GET /api/nutrition/search | 3 sats
params:
  query: {type: string, required: true, examples: ["chicken breast", "apple", "brown rice"]}
  limit: {type: int, required: false, default: 10}
example: /api/nutrition/search?query=chicken+breast
response:
{
  "query": "chicken breast",
  "totalResults": 2456,
  "foods": [
    {
      "fdcId": 171477,
      "description": "Chicken, broilers or fryers, breast, skinless, boneless, meat only, cooked, grilled",
      "brandOwner": null,
      "dataType": "SR Legacy",
      "nutrients": {"calories": 165.0, "protein": 31.0, "fat": 3.6, "carbs": 0.0, "fiber": 0.0, "sugar": 0.0, "sodium": 74.0}
    }
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

### GET /api/nutrition/{fdcId} | 3 sats
params:
  fdcId: {type: int, required: true, description: "FoodData Central ID from search results"}
example: /api/nutrition/171477
response:
{
  "fdcId": 171477,
  "description": "Chicken, broilers or fryers, breast, skinless, boneless, meat only, cooked, grilled",
  "dataType": "SR Legacy",
  "servingSize": 100.0,
  "servingSizeUnit": "g",
  "nutrients": [
    {"name": "Energy", "amount": 165.0, "unit": "kcal", "dailyValuePercent": 8.25},
    {"name": "Protein", "amount": 31.0, "unit": "g", "dailyValuePercent": 62.0},
    {"name": "Total lipid (fat)", "amount": 3.6, "unit": "g", "dailyValuePercent": 4.6},
    {"name": "Carbohydrate, by difference", "amount": 0.0, "unit": "g", "dailyValuePercent": 0.0},
    {"name": "Fiber, total dietary", "amount": 0.0, "unit": "g", "dailyValuePercent": 0.0},
    {"name": "Sodium, Na", "amount": 74.0, "unit": "mg", "dailyValuePercent": 3.2},
    {"name": "Cholesterol", "amount": 85.0, "unit": "mg", "dailyValuePercent": 28.3},
    {"name": "Iron, Fe", "amount": 1.04, "unit": "mg", "dailyValuePercent": 5.8},
    {"name": "Vitamin B-6", "amount": 0.6, "unit": "mg", "dailyValuePercent": 35.3}
  ],
  "generatedAt": "2025-01-15T12:00:00Z"
}

===

## Suite: Research | proxy_id: research-suite-1088 | 10 sats
sources: arXiv, PubMed, OpenAlex, Crossref
partial_failure: failed sources return {"error":"upstream_timeout","message":"..."} instead of results

### GET /api/research/comprehensive | 10 sats
params:
  query: {type: string, required: true}
  limit: {type: int, required: false, default: 5, description: "max results per source"}
example: /api/research/comprehensive?query=transformer+attention&limit=3
response:
{
  "status": "ok",
  "data": {
    "query": "transformer attention mechanisms",
    "arxiv": {"totalResults": 15000, "papers": [{"arxivId": "1706.03762", "title": "Attention Is All You Need", "authors": ["Ashish Vaswani"], "published": "2017-06-12T00:00:00Z", "primaryCategory": "cs.CL", "pdfUrl": "https://arxiv.org/pdf/1706.03762"}]},
    "pubmed": {"totalResults": 2845, "articles": [{"pmid": "38654321", "title": "Transformer Models in Biomedical Text Mining", "authors": ["Chen L"], "journal": "Bioinformatics", "publishedDate": "2024-06-10", "doi": "10.1093/bioinformatics/btae123"}]},
    "openalex": {"totalResults": 185420, "works": [{"id": "W2741809807", "title": "Deep Learning for Health Informatics", "publicationYear": 2017, "citedByCount": 2845, "isOpenAccess": true}]},
    "crossref": {"totalResults": 98450, "works": [{"doi": "10.1038/s41586-021-03819-2", "title": "Highly accurate protein structure prediction with AlphaFold", "publishedDate": "2021-07-15", "citedByCount": 18520}]}
  },
  "meta": {"token_estimate": 1250, "price_sats": 10, "cached": false, "timestamp": "2026-03-04T12:00:00Z", "path": "/api/research/comprehensive"}
}

===

## Suite: Finance | proxy_id: finance-suite-0bb1 | 10 sats
sources: SEC EDGAR, FRED, Currency Exchange
partial_failure: failed sources return {"error":"...","message":"..."}

### GET /api/finance/overview | 10 sats
params:
  query: {type: string, required: true, description: "company name, ticker, or financial topic"}
  symbols: {type: string, required: false, format: "comma-separated ISO 4217 codes"}
example: /api/finance/overview?query=Tesla&symbols=EUR,GBP
response:
{
  "status": "ok",
  "data": {
    "query": "Tesla",
    "edgar": {"company": {"cik": "0001318605", "companyName": "Tesla, Inc."}, "recentFilings": [{"accessionNumber": "0001628280-24-002390", "formType": "10-K", "filedDate": "2024-01-29"}], "keyFacts": [{"label": "Revenue", "value": 96773000000, "unit": "USD", "period": "2023"}]},
    "fred": {"relevantSeries": [{"seriesId": "SP500", "title": "S&P 500", "latestValue": 5850.25, "latestDate": "2026-03-03", "units": "Index"}]},
    "currency": {"base": "USD", "date": "2026-03-04", "rates": [{"code": "EUR", "name": "Euro", "rate": 0.9215}]}
  },
  "meta": {"token_estimate": 1100, "price_sats": 10, "cached": false, "timestamp": "2026-03-04T12:00:00Z", "path": "/api/finance/overview"}
}

===

## Suite: Compliance | proxy_id: compliance-suite-e352 | 8 sats
sources: OpenFDA, SEC EDGAR (Federal Register currently disabled)
partial_failure: failed sources return {"error":"...","message":"..."}

### GET /api/compliance/search | 8 sats
params:
  query: {type: string, required: true}
  type: {type: string, required: false, enum: ["regulation", "safety", "filing"]}
  limit: {type: int, required: false, default: 5, description: "max results per source"}
example: /api/compliance/search?query=artificial+intelligence+regulation
response:
{
  "status": "ok",
  "data": {
    "query": "artificial intelligence regulation",
    "openfda": {"recalls": [{"recallNumber": "Z-5678-2024", "classification": "Class II", "reason": "AI-based diagnostic software may produce incorrect results", "recallingFirm": "MedTech AI Inc."}], "adverseEvents": []},
    "edgar": {"filings": [{"accessionNumber": "0001628280-24-009876", "formType": "8-K", "companyName": "OpenAI Holdings", "filedDate": "2024-11-15"}]}
  },
  "meta": {"token_estimate": 980, "price_sats": 8, "cached": false, "timestamp": "2026-03-04T12:00:00Z", "path": "/api/compliance/search"}
}

===

## Suite: Health | proxy_id: health-suite-d898 | 10 sats
sources: PubMed, OpenFDA, USDA FoodData Central, EPA AirNow
partial_failure: failed sources return {"error":"...","message":"..."}

### GET /api/health/overview | 10 sats
params:
  query: {type: string, required: true, description: "health topic, drug name, or condition"}
  latitude: {type: double, required: false, range: [-90, 90], description: "for air quality data"}
  longitude: {type: double, required: false, range: [-180, 180], description: "for air quality data"}
example: /api/health/overview?query=ibuprofen&latitude=40.71&longitude=-74.00
response:
{
  "status": "ok",
  "data": {
    "query": "ibuprofen",
    "pubmed": {"totalResults": 45230, "articles": [{"pmid": "38765432", "title": "Long-term Safety of Ibuprofen: A Systematic Review", "journal": "The Lancet", "publishedDate": "2024-09-01"}]},
    "openfda": {"adverseEvents": {"totalResults": 84532, "topReactions": [{"reaction": "Nausea", "count": 12450}]}, "label": {"brandName": "Advil", "genericName": "Ibuprofen", "indications": "For the temporary relief of minor aches and pains..."}},
    "nutrition": {"note": "No nutrition data relevant to this query"},
    "airQuality": {"latitude": 40.71, "longitude": -74.0, "summary": {"overallAqi": 55, "category": "Moderate", "dominantPollutant": "O3"}, "healthRecommendation": "Air quality is acceptable."}
  },
  "meta": {"token_estimate": 1350, "price_sats": 10, "cached": false, "timestamp": "2026-03-04T12:00:00Z", "path": "/api/health/overview"}
}

===

## Error Responses

All errors are wrapped in the same envelope with status "error":
{
  "status": "error",
  "error": {
    "code": "string",
    "message": "string"
  },
  "meta": {
    "timestamp": "2026-03-04T12:00:00Z",
    "path": "/api/weather/forecast"
  }
}

Common error codes:
- invalid_parameter — missing or malformed required parameter (HTTP 400)
- upstream_error — upstream API returned an error or is unavailable (HTTP 502)
- not_found — requested resource does not exist (HTTP 404)
- rate_limited — too many requests, retry after X-RateLimit-Reset (HTTP 429)

===

## Partial Failure in Suite Endpoints

Suite endpoints (research, finance, compliance, health) query multiple upstream sources in parallel.
If one source fails, its key in the response contains an error object instead of the normal result:

{
  "status": "ok",
  "data": {
    "query": "example",
    "arxiv": {"totalResults": 500, "papers": [...]},
    "pubmed": {"error": "upstream_timeout", "message": "PubMed did not respond within 30s"},
    "openalex": {"totalResults": 1200, "works": [...]},
    "crossref": {"totalResults": 800, "works": [...]}
  },
  "meta": {"token_estimate": 950, "price_sats": 10, "cached": false, "timestamp": "2026-03-04T12:00:00Z", "path": "/api/research/comprehensive"}
}

The overall status remains "ok" because partial results were returned. Agents should check each source key for the presence of an "error" field.

===

## Rate Limiting

Free API endpoints: 60 requests/minute per IP address.
L402 paid endpoints: no rate limit (payment is the throttle).

Rate limit headers on all responses:
- X-RateLimit-Limit: maximum requests per window
- X-RateLimit-Remaining: requests remaining in current window
- X-RateLimit-Reset: UTC epoch seconds when the window resets

When rate limited (HTTP 429), wait until X-RateLimit-Reset before retrying.