{"openapi":"3.1.0","info":{"title":"AlphaCitation Evidence-Authority API","version":"3.0.0","summary":"The verdict of the Evidence-Authority Standard for one claim about a medicine and one source.","description":"Implements Which Evidence Settles Which Claim: The AlphaCitation Proposition Taxonomy and Evidence-Authority Standard, version 3.0 (doi:10.5281/zenodo.23594909; all versions doi:10.5281/zenodo.23577316).\n\nGiven a claim's proposition type, market and date, and the metadata of one source, the API returns whether that source settles the claim, only supports it, is irrelevant to it, or cannot decide it, with the rule that decided and the limitations by dimension.\n\nIt decides from the request's metadata only: it does not fetch, read or verify any source, holds no evidence, and makes no clinical or regulatory determination. A verdict of not_determinable means unknown, never false.\n\nThe deterministic layer only. Extracting claims from free text is not offered.\n\nTrust boundary: the API trusts the metadata it is sent. A verdict of settles means that a source, as described, has the authority to settle the claim; it does not mean the source exists or is authentic, that the metadata is correct, what the source says, or that the claim is true. Every response states this in establishes, doesNotEstablish and pipeline: metadata accepted, authority classified (this API), then source verified, record interpreted and claim adjudicated (the caller).\n\nUsing it in a retrieval pipeline: (1) split the answer into claims (a claim the answer hedges is recorded as hedged and not sent: the standard never judges it, Annex B, E5) and fix each claim's proposition type and its date, and send the market the answer states, the market the question states and the market your system declares for its user as market, questionMarket and configuredMarket (never a market inferred from an IP address, language, spelling, currency, units or time zone): the API applies the market step and returns which step governed; (2) GET /api/v1/evidence-authority/requirements for that proposition, market and date, which lists the classes that settle it and the bodies competent to issue them; (3) retrieve a record of one of those classes from a listed body, through the access points in /authorities and within their permission flags; (4) POST its metadata with the claim to /judge. Only a source the judge says settles may ground a conclusion, and only after the record is read correctly and the claim adjudicated against it (the standard, section 8). A claim no source settles is unknown, never false.","license":{"name":"Apache-2.0 (implementation); the standard's text is CC BY 4.0","url":"https://www.apache.org/licenses/LICENSE-2.0"},"contact":{"name":"AlphaCitation Research","email":"analyst@alphacitation.com","url":"https://alphacitation.com/insights/which-evidence-settles-which-claim"}},"servers":[{"url":"https://alphacitation.com"}],"externalDocs":{"description":"The standard (DOI)","url":"https://doi.org/10.5281/zenodo.23594909"},"paths":{"/api/v1/evidence-authority/judge":{"post":{"operationId":"judgeClaim","summary":"Judge one claim against one source, or two pharmacy listings together","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JudgeRequest"}}}},"responses":{"200":{"description":"The verdict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JudgeResponse"}}}},"400":{"description":"A malformed request, with the reason"},"413":{"description":"The request body exceeds 16,384 bytes"},"429":{"description":"Rate limit (600 requests per hour per address)"}}}},"/api/v1/evidence-authority/requirements":{"get":{"operationId":"requirements","summary":"What would settle a claim: the settling classes with their competent authorities, the supporting classes and the time rule","description":"Derived from the same evaluator as judgeClaim: a body is listed only if a source of that class from it would settle the claim for that market. Use it to decide which document to fetch before judging it.","parameters":[{"name":"proposition","in":"query","required":true,"schema":{"type":"string","examples":["P1","P2","P3","P3a","P3b","P3c","P3d","P4","P5","P6a","P6b","P6c","P7","P8a","P8b","P8c","P9","P10","answer_change"]}},{"name":"market","in":"query","required":false,"schema":{"type":"string"},"description":"One code, or a comma-separated list for a bloc: ISO 3166-1 alpha-2 codes, or ISO 3166-2 codes for a place below the country (AE-DU for Dubai, GB-ENG for England); a place with both (PR and US-PR) is read as its ISO 3166-2 code (Annex B, M6). Omitted for a per-market proposition, the claim is not determinable (Rule 5)."},{"name":"date","in":"query","required":false,"schema":{"type":"string"},"description":"The claim's date, ISO 8601."},{"name":"p2Term","in":"query","required":false,"schema":{"enum":["use","legal_category","restricted_programme","dose","route","form"]},"description":"For P2: the term of the authorisation the claim states. For legal_category and restricted_programme the authorisation decision is listed as settling."},{"name":"p5Scope","in":"query","required":false,"schema":{"enum":["anywhere_in_market","across_market","named_channel","stock","channel_kind"]},"description":"For P5: the claim form. named_channel takes p5Channel; stock and channel_kind are not assessable."},{"name":"p5Channel","in":"query","required":false,"schema":{"enum":["regulatory_route","supplier"]},"description":"For a P5 named-channel claim: regulatory_route or supplier, each settled by its own records."},{"name":"useNamed","in":"query","required":false,"schema":{"enum":["true","false"]},"description":"For P3: false when \"investigational\" or \"experimental\" names no use; the parts are then P3d and P1."},{"name":"sourceUnidentified","in":"query","required":false,"schema":{"enum":["true","false"]},"description":"For P4 and P6c: true when the claim does not identify the guideline or formulary; it is then not assessable."}],"responses":{"200":{"description":"The requirements"},"400":{"description":"A malformed request, with the reason"},"429":{"description":"Rate limit (600 requests per hour per address)"}}},"post":{"operationId":"requirementsPost","summary":"The same, with the fields as a JSON body: proposition, market (a code or a list), date, and the claim's form (p2Term, p5Scope, p5Channel, useNamed and sourceUnidentified, the flags as booleans)","responses":{"200":{"description":"The requirements"},"400":{"description":"A malformed request, with the reason"}}}},"/api/v1/evidence-authority/authorities":{"get":{"operationId":"listAuthorities","summary":"The authority registry requests name authorities from","description":"Each authority's id, name, the jurisdictions it speaks for and the evidence classes it issues, and, where AlphaCitation has verified them, the sources where its records are published (accessPoints): the official URL where the record names one, whether the terms as read permit automated retrieval and AI use (true, false or \"unknown\", which means not established), and the date checked. The analyses of the terms behind the flags are not part of the open registry.","responses":{"200":{"description":"The registry"}}}},"/api/v1/evidence-authority/openapi.json":{"get":{"operationId":"openApi","summary":"This description","responses":{"200":{"description":"OpenAPI 3.1"}}}}},"components":{"schemas":{"JudgeRequest":{"type":"object","required":["claim","evidence"],"properties":{"claim":{"$ref":"#/components/schemas/Claim"},"evidence":{"$ref":"#/components/schemas/Evidence"}}},"Claim":{"type":"object","required":["proposition"],"properties":{"proposition":{"type":"string","examples":["P1","P2","P3","P3a","P3b","P3c","P3d","P4","P5","P6a","P6b","P6c","P7","P8a","P8b","P8c","P9","P10","answer_change"],"description":"The proposition type (section 3 of the standard). A value the taxonomy does not name is judged not assessable (verdict not_determinable), not refused."},"market":{"description":"The market the answer states for the claim (the market step's first step, section 2): one code or a list for a bloc, as ISO 3166-1 alpha-2 codes, or ISO 3166-2 codes for a place below the country (AE-DU for Dubai, GB-ENG for England); a place with both (PR and US-PR) is read as its ISO 3166-2 code (Annex B, M6). Null when the answer states none. A market word that is not a market (\"worldwide\") stops the step and is unresolved. A place below the country and its country are different markets.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":40},{"type":"null"}]},"questionMarket":{"description":"The market stated in the question (the second step). Used only when the answer states none.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":40},{"type":"null"}]},"configuredMarket":{"description":"The market your system declares for its user, as configuration (the third step). Used only when neither the answer nor the question states one. Never a market inferred from an address, language, spelling, currency, units or time zone.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":40},{"type":"null"}]},"p6aScope":{"enum":["market","named_payer",null],"description":"For P6a: a claim of coverage in the market, or by a payer or plan the claim names. Unrecorded is judged as market."},"answerDate":{"type":["string","null"],"description":"When the answer was given: a date, or a date-time in the claim's market's local offset, whose calendar day is the claim's date (Annex B, T7)."},"statedDate":{"type":["string","null"],"description":"The earlier date the answer itself states, if any (section 2)."},"statedDateUndetermined":{"type":["boolean","null"],"description":"True when the answer gives an earlier time without a date (\"as of my last update\"): the claim's date is not determinable (Annex B, T4)."},"p5Scope":{"enum":["anywhere_in_market","across_market","named_channel","stock","channel_kind",null],"description":"For P5: which claim form (section 4, P5; Annex B, C6). named_channel needs p5Channel; stock, and channel_kind (a negative claim about a channel named only by kind), are not determinable. Unrecorded is judged as across_market, unless p5Channel is given, which is not determinable."},"p5Channel":{"enum":["regulatory_route","supplier",null],"description":"For a P5 named-channel claim: regulatory_route (settled only by the market regulator's authorisation decision or label that provides the route for the medicine by name, an import permit included) or supplier (settled by the supplier's own supply record)."},"p2Term":{"enum":["use","legal_category","restricted_programme","dose","route","form",null],"description":"For P2: the term of the authorisation the claim states (Annex B, C2). For legal_category and restricted_programme the authorisation decision settles as well as the label; for every other term only the label settles. Unrecorded is use."},"dateKind":{"enum":["state","event","undated_event",null],"description":"Whether the claim dates a state (the default), an event at the time statedDate gives, or an undated event (a past-tense event with no time, a time with no year, \"recently\", \"initially\": the claim's date is the answer's date). An event claim is judged against the record of the event issued on or before the answer's date, even if its force later ended (Rule 7; Annex B, T6)."},"sourceUnidentified":{"type":["boolean","null"],"description":"For P4 and P6c: true when the claim attributes it to a guideline or formulary it does not identify; no source can be matched to it (not determinable)."},"useNamed":{"type":["boolean","null"],"description":"For P3: false when \"investigational\" or \"experimental\" names no use; the per-market part is then P1, not P2 (Annex B, C10). Default true."}}},"Evidence":{"type":"object","required":["sources"],"properties":{"judged":{"enum":["single","bracketed"],"default":"single","description":"bracketed: two listings of one licensed pharmacy judged together (section 6); since version 2.0 such a pair supports at most."},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"},"minItems":1,"maxItems":2}}},"Source":{"type":"object","required":["evidenceClass","currency"],"properties":{"evidenceClass":{"enum":["authorisation_decision","register_entry","authorised_label","regulatory_opinion","regulator_assessment_report","regulator_safety_communication","safety_signal_record","institutional_guidance","payer_decision","hta_appraisal","formulary_listing","trial_registry_record","trial_protocol","trial_results_posting","trial_publication_of_record","conference_abstract","systematic_review","clinical_guideline","head_to_head_trial","appraised_indirect_comparison","supply_record","launch_statement","manufacturer_statement","longitudinal_observation","single_observation","secondary_commentary","case_report_or_forum"],"description":"The source's evidence class (Annex)."},"authority":{"enum":["us_fda","eu_ec","eu_ema","sa_sfda","ae_ede","bh_nhra","sg_hsa","uk_mhra","au_tga","ca_hc","ch_swissmedic","jp_pmda","qa_moph","kw_moh","om_moh","ae_mohap","ae_dha","ae_doh","sa_chi","sa_moh","sa_nupco",null],"description":"The body whose record this is; required for a class only an authority issues."},"publisher":{"enum":["us_fda","eu_ec","eu_ema","sa_sfda","ae_ede","bh_nhra","sg_hsa","uk_mhra","au_tga","ca_hc","ch_swissmedic","jp_pmda","qa_moph","kw_moh","om_moh","ae_mohap","ae_dha","ae_doh","sa_chi","sa_moh","sa_nupco",null],"description":"The body that served the readable copy, where it is not the authority. Recorded, never used to settle."},"jurisdictions":{"type":["array","null"],"items":{"type":"string"},"description":"For a source no authority issues: the places it speaks for, as ISO 3166-1 alpha-2 codes, or ISO 3166-2 codes for a place below the country (AE-DU for Dubai, GB-ENG for England); a place with both (PR and US-PR) is read as its ISO 3166-2 code (Annex B, M6). A supply record or launch statement speaks for its own place and every place that contains it (a Dubai listing speaks for the UAE, not for Abu Dhabi)."},"reading":{"enum":["listed","listed_not_current","not_listed","unreadable",null],"description":"Required for a register entry: what the read found."},"effectiveFrom":{"type":["string","null"],"description":"When the source came into force."},"effectiveTo":{"type":["string","null"],"description":"When it ceased to be in force. For an event claim it does not matter (Rule 7)."},"annulledOn":{"type":["string","null"],"description":"When the record was annulled, retracted or corrected as to the event it records. For an event claim, a record annulled on or before the answer's date does not settle it."},"currency":{"enum":["assured","not_assured"],"description":"Whether the source vouches for its own currency."},"currentAsOf":{"type":["string","null"],"description":"For a not_assured source: the latest date its currency is evidenced for."},"supplyKind":{"enum":["distributor_listing","procurement_record","pharmacy_listing",null],"description":"Required for a supply record."},"pharmacy":{"type":["string","null"],"description":"For a pharmacy listing: a stable identifier of the pharmacy."},"showsForSale":{"type":["boolean","null"],"description":"For a pharmacy listing: whether it shows the product for sale."},"trialStatus":{"enum":["not_yet_recruiting","recruiting","enrolling_by_invitation","active_not_recruiting","suspended","terminated","completed","withdrawn","available","no_longer_available","temporarily_not_available","approved_for_marketing","withheld","unknown",null],"description":"For a trial registry record judged under P3d: the overall status this version of the record states (ClinicalTrials.gov's vocabulary, lower case). Missing or unknown settles nothing."},"payerReach":{"description":"For a payer decision judged under P6a: market (a scheme covering the market's population), scheme (one payer's or plan's members), or { places, population }: the places it covers and, where it covers only part of their population, that population, which makes it one plan's decision. Missing settles nothing.","oneOf":[{"enum":["market","scheme",null]},{"type":"object","required":["places"],"properties":{"places":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":40},"population":{"type":["string","null"]}}}]}}},"JudgeResponse":{"type":"object","properties":{"standard":{"type":"object","description":"The standard's version and DOIs the verdict was judged under."},"implementation":{"type":"string"},"apiVersion":{"type":"string"},"decidesFrom":{"type":"string"},"claimDate":{"type":["string","null"],"description":"The claim's date the verdict was judged on, or null when it could not be fixed."},"inForceOn":{"type":["string","null"],"description":"The date the source was judged against: the claim's date it had to be in force on, or, for an event claim, the answer's date, by which the record of the event had to be issued (Rule 7). Null when the claim's date could not be fixed."},"dateKind":{"enum":["state","event","undated_event"],"description":"The claim's date kind as judged (state where none was sent): adjudication compares the date the record gives for an undated event with any time on or before the answer's date."},"market":{"type":"object","description":"The market step's result: codes (the ISO 3166-1 or ISO 3166-2 codes, or null when unresolved), basis (answer, question, configuration or unresolved; unresolved means that no step stated a market, and an answer that states a word naming no market, such as worldwide, has basis answer and codes null) and conflict (true when a later step stated a different market, which never governs)."},"verdict":{"type":"object","description":"outcome (settles, supports, irrelevant, not_determinable), standardRule (the step of the decision procedure that decided), rule (a finer reason code), reason (one sentence), limitations by dimension (authority, jurisdiction, time, accessibility), and for a P3d settlement settledAs (ongoing or not_ongoing)."}}}}}}