{"openapi":"3.0.0","paths":{"/v1/academic/search":{"post":{"description":"Searches academic works via OpenAlex, falling back to Crossref if OpenAlex cannot fulfil the request.","operationId":"AcademicController_search_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcademicSearchRequestDto"}}}},"responses":{"200":{"description":"Search completed successfully. An empty `results` array is not an error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"openalex:W2741809807"},"title":{"type":"string","example":"The state of OA"},"authors":{"type":"array","items":{"type":"string"},"example":["Heather Piwowar"]},"publicationYear":{"type":"number","nullable":true,"example":2018},"doi":{"type":"string","nullable":true,"example":"10.7717/peerj.4375"},"url":{"type":"string","nullable":true,"example":"https://doi.org/10.7717/peerj.4375"},"journal":{"type":"string","nullable":true,"example":"PeerJ"},"citations":{"type":"number","nullable":true,"example":391},"openAccess":{"type":"boolean","example":true},"source":{"type":"string","example":"openalex"}}}},"meta":{"type":"object","properties":{"count":{"type":"number","example":10}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Search scholarly literature","tags":["Academic"]}},"/v1/academic/work":{"post":{"description":"Looks up a single academic work via OpenAlex, falling back to Crossref if needed.","operationId":"AcademicController_getWork_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcademicWorkRequestDto"}}}},"responses":{"200":{"description":"The work was found.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string","example":"openalex:W2741809807"},"title":{"type":"string","example":"The state of OA"},"authors":{"type":"array","items":{"type":"string"},"example":["Heather Piwowar"]},"publicationYear":{"type":"number","nullable":true,"example":2018},"doi":{"type":"string","nullable":true,"example":"10.7717/peerj.4375"},"url":{"type":"string","nullable":true,"example":"https://doi.org/10.7717/peerj.4375"},"journal":{"type":"string","nullable":true,"example":"PeerJ"},"citations":{"type":"number","nullable":true,"example":391},"openAccess":{"type":"boolean","example":true},"source":{"type":"string","example":"openalex"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation (e.g. malformed DOI)."},"404":{"description":"No work exists for the given DOI."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Retrieve a scholarly work by DOI","tags":["Academic"]}},"/v1/news/search":{"post":{"description":"Searches recent news coverage via GDELT.","operationId":"NewsController_search_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsSearchRequestDto"}}}},"responses":{"200":{"description":"Search completed successfully. An empty `results` array is not an error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","example":"Example headline"},"url":{"type":"string","example":"https://example.com/article"},"source":{"type":"string","nullable":true,"example":"example.com"},"publishedAt":{"type":"string","nullable":true,"example":"2023-01-15T12:00:00Z"},"language":{"type":"string","nullable":true,"example":"English"},"country":{"type":"string","nullable":true,"example":"United States"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."},"attribution":{"type":"string","example":"News data provided by the GDELT Project (gdeltproject.org)"}}}}}}}},"400":{"description":"The request failed validation."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Search news articles","tags":["News"]}},"/v1/news/trends":{"post":{"description":"Returns normalized trend volume data for a topic/entity/event via GDELT.","operationId":"NewsController_getTrends_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsTrendsRequestDto"}}}},"responses":{"200":{"description":"Trend data retrieved successfully. An empty `points` array is not an error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"term":{"type":"string","example":"renewable energy"},"points":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"20230101"},"volume":{"type":"number","example":12.3}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."},"attribution":{"type":"string","example":"News data provided by the GDELT Project (gdeltproject.org)"}}}}}}}},"400":{"description":"The request failed validation."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Get news trend volume for a topic","tags":["News"]}},"/v1/crypto/price":{"post":{"description":"Returns current price and 24h change for one or more assets via CoinGecko.","operationId":"CryptoController_getPrices_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoAssetsRequestDto"}}}},"responses":{"200":{"description":"Prices retrieved. Any requested asset CoinGecko did not recognize is listed in `missing`, never silently dropped.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"assets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"bitcoin"},"symbol":{"type":"string","example":"btc"},"price":{"type":"number","nullable":true,"example":104523.42},"currency":{"type":"string","example":"usd"},"change24h":{"type":"number","nullable":true,"example":2.31}}}},"missing":{"type":"array","items":{"type":"string"},"example":[]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Get current cryptocurrency prices","tags":["Crypto"]}},"/v1/crypto/market":{"post":{"description":"Returns broader market data (market cap, rank, volume, supply) for one or more assets via CoinGecko.","operationId":"CryptoController_getMarketData_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CryptoAssetsRequestDto"}}}},"responses":{"200":{"description":"Market data retrieved. Any requested asset CoinGecko did not recognize is listed in `missing`, never silently dropped.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"markets":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"bitcoin"},"symbol":{"type":"string","example":"btc"},"name":{"type":"string","example":"Bitcoin"},"price":{"type":"number","nullable":true,"example":104523.42},"currency":{"type":"string","example":"usd"},"marketCap":{"type":"number","nullable":true,"example":2080000000000},"marketCapRank":{"type":"number","nullable":true,"example":1},"volume24h":{"type":"number","nullable":true,"example":42000000000},"change24h":{"type":"number","nullable":true,"example":2.31},"circulatingSupply":{"type":"number","nullable":true,"example":19800000},"totalSupply":{"type":"number","nullable":true,"example":21000000},"maxSupply":{"type":"number","nullable":true,"example":21000000}}}},"missing":{"type":"array","items":{"type":"string"},"example":[]}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Get cryptocurrency market data","tags":["Crypto"]}},"/v1/fx/rates":{"post":{"description":"Returns current or historical foreign exchange reference rates via Frankfurter (European Central Bank data). These are official daily reference rates, not live trading prices, guaranteed execution prices, exchange quotes, or broker rates.","operationId":"FxController_getRates_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FxRatesRequestDto"}}}},"responses":{"200":{"description":"Reference rates retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"base":{"type":"string","example":"USD"},"date":{"type":"string","example":"2026-09-15"},"rates":{"type":"object","additionalProperties":{"type":"number"},"example":{"EUR":0.85,"GBP":0.74,"NGN":1530.22}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation, or a requested currency is not supported."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Get foreign exchange reference rates","tags":["FX"]}},"/v1/weather":{"post":{"description":"Returns current conditions and a daily forecast via Open-Meteo. This is forecast/reference weather information, not a guaranteed real-time observation - precision depends entirely on the underlying Open-Meteo model data. Hourly forecasts are not currently supported.","operationId":"WeatherController_getForecast_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WeatherRequestDto"}}}},"responses":{"200":{"description":"Forecast retrieved successfully.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"location":{"type":"object","properties":{"latitude":{"type":"number","example":6.5244},"longitude":{"type":"number","example":3.3792},"timezone":{"type":"string","nullable":true,"example":"Africa/Lagos"}}},"current":{"type":"object","nullable":true,"properties":{"time":{"type":"string","example":"2026-09-16T12:00"},"temperature":{"type":"number","nullable":true,"example":27.4},"humidity":{"type":"number","nullable":true,"example":80},"windSpeed":{"type":"number","nullable":true,"example":12.4},"precipitation":{"type":"number","nullable":true,"example":0},"weatherCode":{"type":"number","nullable":true,"example":3}}},"daily":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-09-16"},"temperatureMax":{"type":"number","nullable":true,"example":30.1},"temperatureMin":{"type":"number","nullable":true,"example":24},"weatherCode":{"type":"number","nullable":true,"example":3}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Get a weather forecast for a coordinate","tags":["Weather"]}},"/v1/geocode":{"post":{"description":"Resolves a place name to coordinates (mode \"forward\") or coordinates to a place (mode \"reverse\") via Photon.","operationId":"GeocodeController_geocode_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeocodeRequestDto"}}}},"responses":{"200":{"description":"Geocoding completed successfully. An empty `results` array is not an error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true,"example":"27565124"},"name":{"type":"string","nullable":true,"example":"Lagos"},"street":{"type":"string","nullable":true},"houseNumber":{"type":"string","nullable":true},"city":{"type":"string","nullable":true,"example":"Lagos"},"state":{"type":"string","nullable":true,"example":"Lagos"},"country":{"type":"string","nullable":true,"example":"Nigeria"},"countryCode":{"type":"string","nullable":true,"example":"NG"},"postcode":{"type":"string","nullable":true},"latitude":{"type":"number","example":6.5244},"longitude":{"type":"number","example":3.3792},"type":{"type":"string","nullable":true,"example":"city"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Forward or reverse geocode","tags":["Geocode"]}},"/v1/holidays":{"post":{"description":"Returns public holidays for a country/year via Nager.Date.","operationId":"HolidaysController_getHolidays_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HolidaysRequestDto"}}}},"responses":{"200":{"description":"Holidays retrieved successfully. A recognized country/year with no public holidays on record returns an empty `holidays` array, which is not an error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"country":{"type":"string","example":"NG"},"year":{"type":"number","example":2026},"holidays":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","example":"2026-10-01"},"name":{"type":"string","example":"National Day"},"localName":{"type":"string","example":"National Day"},"countryCode":{"type":"string","example":"NG"},"global":{"type":"boolean","example":true},"counties":{"type":"array","items":{"type":"string"},"nullable":true},"types":{"type":"array","items":{"type":"string"},"nullable":true,"example":["Public"]}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation, or the country code is well-formed but not recognized by Nager.Date."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Get public holidays for a country and year","tags":["Holidays"]}},"/v1/knowledge/search":{"post":{"description":"Searches Wikidata for entities matching a free-text query. This is a general entity/knowledge search, not an authoritative fact-checking system - results reflect whatever is currently in Wikidata and are not guaranteed to be complete, current, or correct for every topic.","operationId":"KnowledgeController_search_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/KnowledgeSearchRequestDto"}}}},"responses":{"200":{"description":"Search completed successfully. An empty `results` array is not an error.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","example":"Q8673"},"name":{"type":"string","example":"Lagos"},"description":{"type":"string","nullable":true,"example":"city in Lagos State, Nigeria"},"url":{"type":"string","example":"https://www.wikidata.org/wiki/Q8673"},"source":{"type":"string","example":"wikimedia"}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."},"attribution":{"type":"string","example":"Data from Wikidata, available under CC0"}}}}}}}},"400":{"description":"The request failed validation."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Search for a knowledge entity","tags":["Knowledge"]}},"/v1/government/census":{"post":{"description":"Queries a constrained subset of US Census Bureau datasets (currently: acs/acs1, acs/acs5). This capability targets US Census data specifically - it is not a general worldwide government-data API, and it is not an unrestricted proxy to the full Census API (allowed datasets, variable count, and geography syntax are all constrained). Data is public domain (US government work), but Callrack does not own or guarantee the underlying figures.","operationId":"GovernmentController_query_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CensusQueryRequestDto"}}}},"responses":{"200":{"description":"Query completed successfully. A valid query matching no rows returns an empty `rows` array.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"dataset":{"type":"string","example":"acs/acs1"},"year":{"type":"number","example":2021},"columns":{"type":"array","items":{"type":"string"},"example":["NAME","B01001_001E"]},"rows":{"type":"array","items":{"type":"object","additionalProperties":{"type":"string"},"example":{"NAME":"California","B01001_001E":"39029342"}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."},"source":{"type":"string","example":"us-census"}}}}}}}},"400":{"description":"The request failed validation (e.g. unsupported dataset, malformed geography, or too many variables)."},"429":{"description":"The upstream provider is rate-limiting requests."},"502":{"description":"The upstream provider is unavailable."},"504":{"description":"The upstream provider timed out."}},"summary":"Query US Census Bureau statistical data","tags":["Government"]}},"/v1/research":{"post":{"description":"Composes existing Callrack capabilities (academic, news, knowledge, and optionally government) into a single research result for a given query. Supported sources: academic, news, knowledge, government. This endpoint gathers and structures evidence - it does not generate an AI-written narrative answer. One source failing does not fail the whole request: check each source's own `status`, and the top-level `status` (\"complete\" | \"partial\" | \"failed\") for the overall outcome. The HTTP status is always 200 for a successfully *executed* research request, even when some or all sources failed - the response body always carries the true per-source and overall outcome.","operationId":"ResearchController_research_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchRequestDto"}}}},"responses":{"200":{"description":"Research executed. Check `data.status` and each source's `status` for the actual outcome.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string","example":"renewable energy investment in Africa"},"status":{"type":"string","enum":["complete","partial","failed"],"example":"complete"},"sources":{"type":"object","properties":{"academic":{"type":"object","properties":{"status":{"type":"string","enum":["success","empty","failed"],"example":"success"},"data":{"type":"object","nullable":true,"description":"The underlying capability response - shape varies by source."},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","example":"PROVIDER_UNAVAILABLE"},"message":{"type":"string","example":"The upstream provider is currently unavailable. Please try again later."}}}}},"news":{"type":"object","properties":{"status":{"type":"string","enum":["success","empty","failed"],"example":"success"},"data":{"type":"object","nullable":true,"description":"The underlying capability response - shape varies by source."},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","example":"PROVIDER_UNAVAILABLE"},"message":{"type":"string","example":"The upstream provider is currently unavailable. Please try again later."}}}}},"knowledge":{"type":"object","properties":{"status":{"type":"string","enum":["success","empty","failed"],"example":"success"},"data":{"type":"object","nullable":true,"description":"The underlying capability response - shape varies by source."},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","example":"PROVIDER_UNAVAILABLE"},"message":{"type":"string","example":"The upstream provider is currently unavailable. Please try again later."}}}}},"government":{"type":"object","properties":{"status":{"type":"string","enum":["success","empty","failed"],"example":"success"},"data":{"type":"object","nullable":true,"description":"The underlying capability response - shape varies by source."},"error":{"type":"object","nullable":true,"properties":{"code":{"type":"string","example":"PROVIDER_UNAVAILABLE"},"message":{"type":"string","example":"The upstream provider is currently unavailable. Please try again later."}}}}}}},"findings":{"type":"array","description":"academic/news/knowledge results normalized into provenance-preserving evidence items (government is excluded - see composition.sourcesRequested for whether it ran).","items":{"type":"object"}},"disagreements":{"type":"array","items":{"type":"object"}},"composition":{"type":"object","properties":{"sourcesRequested":{"type":"array","items":{"type":"string"}},"sourcesSucceeded":{"type":"array","items":{"type":"string"}},"sourcesEmpty":{"type":"array","items":{"type":"string"}},"sourcesFailed":{"type":"array","items":{"type":"string"}},"retrievedAt":{"type":"string","format":"date-time"}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."},"sourcesUsed":{"type":"array","items":{"type":"string"},"example":["academic","news","knowledge"]},"price":{"type":"object","nullable":true,"properties":{"amount":{"type":"string"},"currency":{"type":"string","example":"USDC"}}}}}}}}}},"400":{"description":"The request failed validation (e.g. unsupported source name, too many sources, or \"government\" selected without its required dataset/year/variables/forGeography options)."}},"summary":"Aggregate research data across Callrack capabilities","tags":["Research"]}},"/v1/capabilities":{"get":{"description":"Returns the same capability metadata (name, description, category, price, request/response schema) that powers x402 Bazaar discovery - the canonical, always-current source for the Callrack web app and any other client. Never requires payment.","operationId":"CapabilitiesController_list_v1","parameters":[],"responses":{"200":{"description":"The current capability list and active network."}},"summary":"List every public Callrack capability","tags":["Capabilities"]}},"/v1/verify":{"post":{"description":"Gathers real evidence from academic, news, and knowledge search (deterministic composition, the same pattern research/evidence/compare use) and classifies each relevant item as affirming or denying the claim using explainable lexical term-overlap and negation-cue heuristics - never an LLM, never semantic entailment. `verdict`/`confidence` describe how the actually-returned evidence reads, not an independent fact-check; every evidence item traces to a real capability result, with a request ID.","operationId":"VerifyController_verify_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyRequestDto"}}}},"responses":{"200":{"description":"Verification executed. `sourcesChecked: 0` (verdict \"insufficient\") means no relevant evidence was found, not that the claim is false.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"claim":{"type":"string"},"verdict":{"type":"string","enum":["supported","contradicted","mixed","insufficient"]},"confidence":{"type":"number","minimum":0,"maximum":1},"evidence":{"type":"array","items":{"type":"object","properties":{"source":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","nullable":true},"provider":{"type":"string","example":"news.search"}}},"excerpt":{"type":"string","nullable":true},"retrievedAt":{"type":"string","format":"date-time"},"data":{"type":"object","nullable":true,"description":"Additional real fields from the source, when available."}}}},"agreementCount":{"type":"integer"},"contradictionCount":{"type":"integer"},"sourcesChecked":{"type":"integer"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation (e.g. claim too short, unsupported sourceTypes value)."}},"summary":"Verify a claim against existing Callrack capabilities","tags":["Information"]}},"/v1/evidence":{"post":{"description":"Gathers real results from existing Callrack capabilities (academic, news, knowledge) and returns them with full provenance - never an AI-generated narrative answer. Every finding traces to a real capability result and carries its own source, retrieval timestamp, and (when the underlying capability returned one) an excerpt plus additional structured fields.","operationId":"EvidenceController_evidence_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvidenceRequestDto"}}}},"responses":{"200":{"description":"Evidence gathered. `findings` may be empty when no source returned a matching result - this is never padded with a fabricated finding.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"findings":{"type":"array","items":{"type":"object","properties":{"source":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","nullable":true},"provider":{"type":"string","example":"academic.search"}}},"excerpt":{"type":"string","nullable":true},"retrievedAt":{"type":"string","format":"date-time"},"data":{"type":"object","nullable":true}}}},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","nullable":true},"provider":{"type":"string"}}}},"retrievedAt":{"type":"string","format":"date-time"}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation (e.g. query too short, unsupported sourceTypes value)."}},"summary":"Return a machine-readable evidence pack for a query","tags":["Information"]}},"/v1/compare":{"post":{"description":"Runs a query across academic, news, and knowledge search and returns the distinct subjects found, a flattened table of real attribute values per subject, the deduplicated source list, and any detected disagreements (the same-titled subject described differently by two results). Never fabricates a value a provider did not return - an empty `attributes`/`disagreements` array for a subject is a correct result.","operationId":"CompareController_compare_v1","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompareRequestDto"}}}},"responses":{"200":{"description":"Comparison executed.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"query":{"type":"string"},"subjects":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"sources":{"type":"array","items":{"type":"string"}}}}},"attributes":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"string"},"key":{"type":"string"},"value":{"type":"string"},"provider":{"type":"string"}}}},"sources":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string"},"url":{"type":"string","nullable":true},"provider":{"type":"string"}}}},"disagreements":{"type":"array","items":{"type":"object","properties":{"subject":{"type":"string"},"attribute":{"type":"string"},"values":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"source":{"type":"object"}}}}}}}}},"meta":{"type":"object","properties":{"requestId":{"type":"string","example":"req_1a2b3c..."}}}}}}}},"400":{"description":"The request failed validation (e.g. query too short, unsupported sourceTypes value)."}},"summary":"Compare information gathered from multiple Callrack capabilities","tags":["Information"]}},"/health":{"get":{"description":"Verifies that the Callrack API process is alive and responsive.","operationId":"HealthController_getHealth","parameters":[],"responses":{"200":{"description":"System is healthy and responsive.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string","example":"0.1.0"},"uptime":{"type":"number","example":123},"timestamp":{"type":"string","example":"2026-09-16T19:00:00.000Z"}}}}}}},"summary":"Health check","tags":["System"]}},"/health/ready":{"get":{"description":"Verifies that required infrastructure (PostgreSQL, Redis) is reachable.","operationId":"HealthController_getReadiness","parameters":[],"responses":{"200":{"description":"All required infrastructure is reachable."},"503":{"description":"One or more required infrastructure dependencies are unreachable."}},"summary":"Readiness check","tags":["System"]}}},"info":{"title":"Callrack API","description":"Callrack pay-per-use information infrastructure platform API","version":"0.1.0","contact":{}},"tags":[],"servers":[],"components":{"securitySchemes":{"x-request-id":{"type":"apiKey","in":"header","name":"x-request-id","description":"Optional client request ID for distributed tracing"}},"schemas":{"AcademicSearchRequestDto":{"type":"object","properties":{"query":{"type":"string","description":"Free-text search query.","example":"large language models healthcare","minLength":1,"maxLength":500},"limit":{"type":"number","description":"Maximum number of results to return.","example":10,"minimum":1,"maximum":50,"default":10}},"required":["query"]},"AcademicWorkRequestDto":{"type":"object","properties":{"doi":{"type":"string","description":"Digital Object Identifier (DOI) of the work.","example":"10.7717/peerj.4375"}},"required":["doi"]},"NewsSearchRequestDto":{"type":"object","properties":{"query":{"type":"string","description":"Free-text search query.","example":"renewable energy Africa","minLength":1,"maxLength":500},"limit":{"type":"number","description":"Maximum number of articles to return.","example":10,"minimum":1,"maximum":50,"default":10}},"required":["query"]},"NewsTrendsRequestDto":{"type":"object","properties":{"query":{"type":"string","description":"Topic, entity, or event to retrieve trend volume for.","example":"renewable energy","minLength":1,"maxLength":500},"timespan":{"type":"string","description":"GDELT timespan window (e.g. \"1d\", \"7d\", \"1m\"). Defaults to \"7d\".","example":"7d"}},"required":["query"]},"CryptoAssetsRequestDto":{"type":"object","properties":{"assets":{"description":"CoinGecko asset identifiers (lowercase slugs, e.g. \"bitcoin\").","example":["bitcoin","ethereum"],"minItems":1,"maxItems":20,"type":"array","items":{"type":"string"}},"currency":{"type":"string","description":"Quote currency (ISO-style 3-letter code, lowercase).","example":"usd","default":"usd"}},"required":["assets"]},"FxRatesRequestDto":{"type":"object","properties":{"base":{"type":"string","description":"Base currency (ISO-style 3-letter code).","example":"USD"},"currencies":{"description":"Target currencies to quote against the base currency.","example":["EUR","GBP","NGN"],"minItems":1,"maxItems":20,"type":"array","items":{"type":"string"}},"date":{"type":"string","description":"Historical date (YYYY-MM-DD) for reference rates as of that day. Omit for the latest available reference rates.","example":"2026-09-15"}},"required":["base","currencies"]},"WeatherRequestDto":{"type":"object","properties":{"latitude":{"type":"number","description":"Latitude in decimal degrees.","example":6.5244,"minimum":-90,"maximum":90},"longitude":{"type":"number","description":"Longitude in decimal degrees.","example":3.3792,"minimum":-180,"maximum":180},"days":{"type":"number","description":"Number of days of daily forecast to include.","example":3,"minimum":1,"maximum":16,"default":3}},"required":["latitude","longitude"]},"GeocodeRequestDto":{"type":"object","properties":{"mode":{"type":"string","description":"Which geocoding operation to perform.","enum":["forward","reverse"],"example":"forward"},"query":{"type":"string","description":"Free-text place query. Required when mode is \"forward\".","example":"Lagos, Nigeria","minLength":1,"maxLength":200},"limit":{"type":"number","description":"Maximum number of results to return. Only used when mode is \"forward\".","example":5,"minimum":1,"maximum":20,"default":5},"latitude":{"type":"number","description":"Latitude in decimal degrees. Required when mode is \"reverse\".","example":6.5244,"minimum":-90,"maximum":90},"longitude":{"type":"number","description":"Longitude in decimal degrees. Required when mode is \"reverse\".","example":3.3792,"minimum":-180,"maximum":180}},"required":["mode"]},"HolidaysRequestDto":{"type":"object","properties":{"country":{"type":"string","description":"ISO 3166-1 alpha-2 country code.","example":"NG"},"year":{"type":"number","description":"Calendar year.","example":2026,"minimum":1900,"maximum":2100}},"required":["country","year"]},"KnowledgeSearchRequestDto":{"type":"object","properties":{"query":{"type":"string","description":"Free-text entity/knowledge search query.","example":"Lagos","minLength":1,"maxLength":200},"limit":{"type":"number","description":"Maximum number of results to return.","example":10,"minimum":1,"maximum":20,"default":10},"language":{"type":"string","description":"ISO-style language code for labels/descriptions (e.g. \"en\", \"fr\").","example":"en","default":"en"}},"required":["query"]},"CensusQueryRequestDto":{"type":"object","properties":{"dataset":{"type":"string","description":"Which Census dataset to query.","enum":["acs/acs1","acs/acs5"],"example":"acs/acs1"},"year":{"type":"number","description":"Data year for the dataset vintage.","example":2021,"minimum":2009,"maximum":2035},"variables":{"description":"Census variable codes to retrieve (e.g. \"NAME\", \"B01001_001E\").","example":["NAME","B01001_001E"],"minItems":1,"maxItems":10,"type":"array","items":{"type":"string"}},"forGeography":{"type":"string","description":"A single Census geography clause (e.g. \"state:*\", \"state:06\", \"county:*\"). Chained clauses (\"&in=...\") are not supported in this initial capability.","example":"state:*","minLength":3,"maxLength":100}},"required":["dataset","year","variables","forGeography"]},"ResearchGovernmentOptionsDto":{"type":"object","properties":{"dataset":{"type":"string","description":"Which Census dataset to query.","enum":["acs/acs1","acs/acs5"],"example":"acs/acs1"},"year":{"type":"number","description":"Data year for the dataset vintage.","example":2021,"minimum":2009,"maximum":2035},"variables":{"description":"Census variable codes to retrieve (e.g. \"NAME\", \"B01001_001E\").","example":["NAME","B01001_001E"],"minItems":1,"maxItems":10,"type":"array","items":{"type":"string"}},"forGeography":{"type":"string","description":"A single Census geography clause (e.g. \"state:*\", \"state:06\").","example":"state:*","minLength":3,"maxLength":100}},"required":["dataset","year","variables","forGeography"]},"ResearchRequestDto":{"type":"object","properties":{"query":{"type":"string","description":"The research question or topic to gather information about.","example":"renewable energy investment in Africa","minLength":3,"maxLength":500},"sources":{"type":"array","description":"Which Callrack capabilities to consult. Defaults to academic + news + knowledge when omitted. \"government\" additionally requires the `government` options object.","example":["academic","news","knowledge"],"minItems":1,"maxItems":4,"items":{"type":"string","enum":["academic","news","knowledge","government"]}},"limit":{"type":"number","description":"Maximum number of results requested from each search-based source.","example":5,"minimum":1,"maximum":10,"default":5},"government":{"description":"Required when `sources` includes \"government\"; ignored otherwise.","allOf":[{"$ref":"#/components/schemas/ResearchGovernmentOptionsDto"}]}},"required":["query"]},"VerifyRequestDto":{"type":"object","properties":{"claim":{"type":"string","description":"The claim to verify.","example":"Nigeria is the most populous country in Africa.","minLength":5,"maxLength":500},"sourceTypes":{"type":"array","description":"Which Callrack capabilities to check for relevant evidence. Defaults to academic + news + knowledge.","example":["academic","news","knowledge"],"minItems":1,"maxItems":3,"items":{"type":"string","enum":["academic","news","knowledge"]}},"maxSources":{"type":"number","description":"Maximum total evidence items to consider across every checked source.","example":12,"minimum":3,"maximum":30,"default":12}},"required":["claim"]},"EvidenceRequestDto":{"type":"object","properties":{"query":{"type":"string","description":"The topic or question to gather a machine-readable evidence pack about.","example":"renewable energy investment in Africa","minLength":3,"maxLength":500},"sourceTypes":{"type":"array","description":"Which Callrack capabilities to consult. Defaults to academic + news + knowledge.","example":["academic","news","knowledge"],"minItems":1,"maxItems":3,"items":{"type":"string","enum":["academic","news","knowledge"]}},"limit":{"type":"number","description":"Maximum number of results requested from each consulted source.","example":5,"minimum":1,"maximum":10,"default":5}},"required":["query"]},"CompareRequestDto":{"type":"object","properties":{"query":{"type":"string","description":"The topic or entity name to gather and compare information about.","example":"Tesla","minLength":2,"maxLength":200},"sourceTypes":{"type":"array","description":"Which Callrack capabilities to consult. Defaults to academic + news + knowledge.","example":["academic","news","knowledge"],"minItems":1,"maxItems":3,"items":{"type":"string","enum":["academic","news","knowledge"]}},"limit":{"type":"number","description":"Maximum number of results requested from each consulted source.","example":5,"minimum":1,"maximum":10,"default":5}},"required":["query"]}}}}