{"openapi":"3.1.0","info":{"title":"Journal RPS published contract","version":"1.1.0","summary":"Read-only paper records, peer review forks, verdicts and the public ledger.","description":"These endpoints are consumed by downstream platforms and are never written through.\n\nEvery verdict response states three things separately and always:\n\n- `result_kind`: whether the record is a `scientific_verdict` or an `editorial_disposition`. The two are never merged, and one is never presented in place of the other.\n- `engine.version`: the `journal_rps` version that computed the result.\n- `aggregated_run_ids`: the execution runs whose observations the result aggregates.\n\nA submission closed for infrastructure failure has an `editorial_disposition` and a null `scientific_verdict`.\nA record with incomplete coverage may not be presented as a passing result; `completeness.coverage_complete` says so explicitly.\n`not_tested` is part of every verdict response and lists what the run did not establish.","contact":{"name":"Journal publisher","url":"https:\/\/journal.bntrg.co.uk\/journal"}},"servers":[{"url":"https:\/\/journal.bntrg.co.uk\/api\/v1"}],"tags":[{"name":"submissions","description":"Public paper records, provenance, lineage, data sources and reproducibility maps."},{"name":"forks","description":"Replication peer review, control evidence and extension lineage."},{"name":"verdicts","description":"Adjudicated results. A scientific verdict and an editorial disposition are separate facts."},{"name":"ledger","description":"Append-only events, content hashes, mirror signatures and tamper evidence."}],"paths":{"\/submissions":{"get":{"tags":["submissions"],"operationId":"listSubmissions","summary":"List public receipts","parameters":[{"name":"state","in":"query","required":false,"description":"Workflow state, as the engine names it.","schema":{"type":"string"}},{"name":"article_type","in":"query","required":false,"description":"original_research, replication and so on.","schema":{"type":"string"}},{"name":"claim_family_id","in":"query","required":false,"description":"Claim family filter.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum rows to return (default 100).","schema":{"type":"integer"}}],"responses":{"200":{"description":"The receipts.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/SubmissionList"}}}}}}},"\/submissions\/{submission}":{"get":{"tags":["submissions"],"operationId":"getSubmission","summary":"One public receipt with its claim map and result summary","parameters":[{"name":"submission","in":"path","required":true,"description":"The public receipt id.","schema":{"type":"uuid"}}],"responses":{"200":{"description":"The receipt.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Submission"}}}},"404":{"description":"No such receipt.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NotFound"}}}}}}},"\/forks":{"get":{"tags":["forks"],"operationId":"listPeerReviewForks","summary":"List replication and extension forks","parameters":[{"name":"paper_id","in":"query","required":false,"description":"Filter by paper public id.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Filter by replication or extension.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum rows to return (default 100).","schema":{"type":"integer"}}],"responses":{"200":{"description":"Forks and their stage attempts.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PeerReviewForkList"}}}}}}},"\/forks\/summary":{"get":{"tags":["forks"],"operationId":"summarisePeerReviewForks","summary":"Counts of registered corpus papers, replication forks and first controls","responses":{"200":{"description":"Current aggregate counts."}}}},"\/forks\/{fork}":{"get":{"tags":["forks"],"operationId":"getPeerReviewFork","summary":"One replication or extension fork with stage evidence","parameters":[{"name":"fork","in":"path","required":true,"description":"The fork public id.","schema":{"type":"uuid"}}],"responses":{"200":{"description":"The fork and its stage attempts.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/PeerReviewFork"}}}},"404":{"description":"No such fork.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NotFound"}}}}}}},"\/verdicts\/{submission}":{"get":{"tags":["verdicts"],"operationId":"getVerdict","summary":"The adjudicated result with per-claim detail and the completeness statement","description":"Returns the latest verdict for a submission. A submission with no adjudicated verdict is a 404, not an empty object: an editorial disposition alone is not a verdict.","parameters":[{"name":"submission","in":"path","required":true,"description":"The public receipt id.","schema":{"type":"uuid"}}],"responses":{"200":{"description":"The adjudicated result.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/Verdict"}}}},"404":{"description":"No adjudicated verdict exists for this receipt.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NoVerdict"}}}}}}},"\/ledger":{"get":{"tags":["ledger"],"operationId":"listLedger","summary":"Append-only events with content hashes and signatures","parameters":[{"name":"event_type","in":"query","required":false,"description":"Event type filter, e.g. verdict.decided.","schema":{"type":"string"}},{"name":"submission_id","in":"query","required":false,"description":"Restrict to one receipt.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum events to return (default 200).","schema":{"type":"integer"}}],"responses":{"200":{"description":"The events, plus a verification of the stored chain.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LedgerList"}}}}}}},"\/ledger\/proof":{"get":{"tags":["ledger"],"operationId":"getLedgerProof","summary":"Tamper evidence: the live chain, the witnessed checkpoint and whether they still agree","description":"Calls the engine on every request. Verification is the point; a proof that skipped it would not be one.","responses":{"200":{"description":"The proof.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/LedgerProof"}}}}}}},"\/openapi.json":{"get":{"tags":["submissions"],"operationId":"getOpenApiDocument","summary":"This document","responses":{"200":{"description":"The OpenAPI document.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/object"}}}}}}}},"components":{"schemas":{"ContractEnvelope":{"type":"object","required":["contract_version","api_version"],"properties":{"contract_version":{"type":"string","examples":["1.1.0"]},"api_version":{"type":"string","examples":["v1"]}}},"ResultKind":{"type":"string","enum":["scientific_verdict","editorial_disposition"],"description":"Which kind of record this is. A consumer must read this before either field."},"SubmissionSummary":{"type":"object","required":["id","title","state","package_hash"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"article_type":{"type":"string"},"abstract":{"type":["string","null"]},"authors":{"type":"array","items":{"type":"string"}},"doi":{"type":["string","null"]},"claim_family_id":{"type":"string"},"subject_category":{"type":"string"},"intake":{"$ref":"#\/components\/schemas\/PaperIntake"},"lineage":{"$ref":"#\/components\/schemas\/PaperLineage"},"data_availability_statement":{"type":["string","null"]},"data_sources":{"type":"array","items":{"$ref":"#\/components\/schemas\/PaperSource"}},"reproducibility_stages":{"type":"array","items":{"$ref":"#\/components\/schemas\/ReproducibilityStage"}},"peer_review_forks":{"type":"array","items":{"$ref":"#\/components\/schemas\/PeerReviewForkSummary"}},"state":{"type":"string"},"revision":{"type":"integer"},"version":{"type":"integer"},"first_receipt_at":{"type":["string","null"],"format":"date-time"},"days_open":{"type":"integer"},"admitted_at":{"type":["string","null"],"format":"date-time"},"decided_at":{"type":["string","null"],"format":"date-time"},"package_hash":{"type":["string","null"]},"plan_hash":{"type":["string","null"]},"plan_version":{"type":["string","null"]},"claims":{"type":"array","items":{"$ref":"#\/components\/schemas\/ClaimCell"}},"result":{"type":["object","null"],"properties":{"id":{"type":"integer"},"result_kind":{"$ref":"#\/components\/schemas\/ResultKind"},"scientific_verdict":{"type":["string","null"]},"editorial_disposition":{"type":"string"},"coverage_complete":{"type":"boolean"},"decided_at":{"type":["string","null"],"format":"date-time"},"engine_version":{"type":"string"},"plan_hash":{"type":"string"},"statistics_hash":{"type":"string"},"publishable_as_adjudicated_result":{"type":"boolean"}}},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"},"verdict_api_url":{"type":"string","format":"uri"}}},"PaperIntake":{"type":"object","required":["method","recorded_by"],"properties":{"method":{"type":"string","enum":["submitted","ingested"]},"source_name":{"type":["string","null"]},"source_identifier":{"type":["string","null"]},"source_url":{"type":["string","null"],"format":"uri"},"recorded_by":{"type":["object","null"],"properties":{"name":{"type":"string"}}},"ingested_at":{"type":["string","null"],"format":"date-time"}}},"PaperLineageRecord":{"type":"object","required":["id","title","url"],"properties":{"id":{"type":"string","format":"uuid"},"title":{"type":"string"},"relationship":{"type":"string"},"url":{"type":"string","format":"uri"}}},"PaperLineage":{"type":"object","required":["relationship","parent","descendants"],"properties":{"relationship":{"type":"string","enum":["original","exact_replication","extension"]},"parent":{"oneOf":[{"$ref":"#\/components\/schemas\/PaperLineageRecord"},{"type":"null"}]},"descendants":{"type":"array","items":{"$ref":"#\/components\/schemas\/PaperLineageRecord"}}}},"PaperSource":{"type":"object","required":["kind","name","uri","access"],"properties":{"kind":{"type":"string","enum":["dataset","code","supplement","protocol"]},"name":{"type":"string"},"uri":{"type":"string"},"identifier":{"type":["string","null"]},"version":{"type":["string","null"]},"checksum_sha256":{"type":["string","null"]},"access":{"type":"string","enum":["open","controlled","provided"]},"metadata":{"type":["object","null"]}}},"ReproducibilityStage":{"type":"object","required":["sequence","type","title","status"],"properties":{"sequence":{"type":"integer"},"type":{"type":"string","enum":["data","analysis","assay"]},"title":{"type":"string"},"description":{"type":["string","null"]},"status":{"type":"string"},"requirements":{"type":["object","array","null"]},"assessment":{"type":["object","array","null"]}}},"Submission":{"allOf":[{"$ref":"#\/components\/schemas\/ContractEnvelope"},{"type":"object","required":["data"],"properties":{"data":{"$ref":"#\/components\/schemas\/SubmissionSummary"}}}]},"PeerReviewForkSummary":{"type":"object","required":["id","type","version","target_result","control_outcome","url","api_url"],"properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["replication","extension"]},"version":{"type":"integer"},"target_result":{"type":"string"},"control_outcome":{"type":["string","null"]},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"}}},"PeerReviewForkRecord":{"type":"object","required":["id","paper_id","type","version","target_result","registered_comparison","stages"],"properties":{"id":{"type":"string","format":"uuid"},"paper_id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["replication","extension"]},"version":{"type":"integer"},"previous_fork_id":{"type":["string","null"],"format":"uuid"},"target_result":{"type":"string"},"registered_comparison":{"type":["object","null"]},"parent_snapshot_hash":{"type":"string"},"control":{"type":["object","null"]},"change_log":{"type":["object","null"]},"stages":{"type":"array","items":{"type":"object"}},"url":{"type":"string","format":"uri"},"api_url":{"type":"string","format":"uri"}}},"PeerReviewFork":{"allOf":[{"$ref":"#\/components\/schemas\/ContractEnvelope"},{"type":"object","required":["data"],"properties":{"data":{"$ref":"#\/components\/schemas\/PeerReviewForkRecord"}}}]},"PeerReviewForkList":{"allOf":[{"$ref":"#\/components\/schemas\/ContractEnvelope"},{"type":"object","required":["data","count"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/PeerReviewForkRecord"}},"count":{"type":"integer"}}}]},"SubmissionList":{"allOf":[{"$ref":"#\/components\/schemas\/ContractEnvelope"},{"type":"object","required":["data","count"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/SubmissionSummary"}},"count":{"type":"integer"}}}]},"ClaimCell":{"type":"object","required":["claim_id","stratum_id","metric","unit"],"properties":{"claim_id":{"type":"string"},"stratum_id":{"type":"string"},"metric":{"type":"string"},"unit":{"type":"string"},"environment":{"type":"string"},"reference_value":{"type":"number"},"narrow_band":{"type":"number"},"wide_band":{"type":"number"},"min_valid_n":{"type":"integer"},"planned_n":{"type":"integer"},"notes":{"type":["string","null"]}}},"VerdictClaim":{"type":"object","required":["claim_id","status","observations"],"properties":{"claim_id":{"type":"string"},"stratum_id":{"type":"string"},"metric":{"type":"string"},"unit":{"type":"string"},"environment":{"type":"string"},"status":{"type":"string","examples":["pass","fail","inconclusive"]},"reason":{"type":["string","null"]},"reference_value":{"type":["number","null"]},"narrow_band":{"type":["number","null"]},"wide_band":{"type":["number","null"]},"planned_n":{"type":["integer","null"]},"valid_n":{"type":["integer","null"]},"min_valid_n":{"type":["integer","null"]},"variance_flagged":{"type":["boolean","null"]},"variance_reason":{"type":["string","null"]},"passed":{"type":["boolean","null"]},"observations":{"type":"array","items":{"type":"object","properties":{"attempt_public_id":{"type":["string","null"]},"seed":{"type":["string","null"]},"value":{"type":["number","null"]},"absolute_delta":{"type":["number","null"]},"within_narrow_band":{"type":["boolean","null"]},"within_wide_band":{"type":["boolean","null"]}}}},"missing":{"type":"array","items":{"type":"object"}}}},"VerdictRecord":{"type":"object","required":["submission_id","result_kind","is_scientific_verdict","scientific_verdict","editorial_disposition","engine","aggregated_run_ids","completeness","not_tested"],"properties":{"submission_id":{"type":"string","format":"uuid"},"submission_title":{"type":"string"},"submission_version":{"type":"integer"},"submission_version_hash":{"type":"string"},"article_type":{"type":"string"},"claim_family_id":{"type":"string"},"state":{"type":"string"},"result_kind":{"$ref":"#\/components\/schemas\/ResultKind"},"is_scientific_verdict":{"type":"boolean"},"scientific_verdict":{"type":"object","required":["verdict","reason","supported_claims","unsupported_claims"],"description":"Null `verdict` means no scientific conclusion was reached. The disposition below still stands, and is not a substitute.","properties":{"verdict":{"type":["string","null"],"examples":["reproduced","reproduced_with_variance","partially_reproduced","not_reproduced","inconclusive_because_infrastructure",null]},"reason":{"type":"string"},"supported_claims":{"type":"array","items":{"type":"string"}},"unsupported_claims":{"type":"array","items":{"type":"string"}}}},"editorial_disposition":{"type":"object","required":["disposition","decided_at","publishable_as_adjudicated_result"],"properties":{"disposition":{"type":"string","examples":["publishable_subject_to_claim_review","pending_recovery_not_a_rejection"]},"decided_at":{"type":["string","null"],"format":"date-time"},"decided_by_role":{"type":"string"},"publishable_as_adjudicated_result":{"type":"boolean"},"note":{"type":"string"}}},"engine":{"type":"object","required":["package","version","plan_hash","statistics_hash"],"properties":{"package":{"type":"string","examples":["journal_rps"]},"version":{"type":"string"},"plan_hash":{"type":"string"},"statistics_hash":{"type":"string"},"verification":{"type":"object"},"provenance":{"type":"object"}}},"aggregated_run_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"completeness":{"type":"object","required":["coverage_complete","registered_runs","runs_with_evidence","statement"],"properties":{"coverage_complete":{"type":"boolean"},"registered_runs":{"type":"integer"},"runs_with_evidence":{"type":"integer"},"missing_runs":{"type":"array","items":{"type":"object"}},"registered_cells":{"type":"integer"},"cells_with_evidence":{"type":"integer"},"statement":{"type":"string"}}},"claims":{"type":"array","items":{"$ref":"#\/components\/schemas\/VerdictClaim"}},"runs":{"type":"array","items":{"$ref":"#\/components\/schemas\/LedgerRun"}},"statistics":{"type":"array","items":{"type":"object"}},"not_tested":{"type":"object","required":["count","items","statement"],"properties":{"count":{"type":"integer"},"items":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"detail":{"type":"string"}}}},"statement":{"type":"string"}}},"supersedes_id":{"type":["integer","null"]},"history":{"type":"array","items":{"type":"object"}}}},"Verdict":{"allOf":[{"$ref":"#\/components\/schemas\/ContractEnvelope"},{"type":"object","required":["data"],"properties":{"data":{"$ref":"#\/components\/schemas\/VerdictRecord"}}}]},"LedgerRun":{"type":"object","required":["id","condition_key","state","produced_evidence"],"properties":{"id":{"type":"string","format":"uuid"},"condition_key":{"type":"string"},"condition_type":{"type":"string"},"condition_order":{"type":"integer"},"stratum_id":{"type":"string"},"environment":{"type":"string"},"state":{"type":"string"},"attempt_count":{"type":"integer"},"accepted_attempt_number":{"type":["integer","null"]},"produced_evidence":{"type":"boolean"},"missing_reasons":{"type":"array","items":{"type":"string"}},"order_hash":{"type":["string","null"]}}},"LedgerSignature":{"type":"object","required":["key_id","algorithm","signature_hex"],"properties":{"key_id":{"type":"string"},"algorithm":{"type":"string"},"signature_hex":{"type":"string"}}},"LedgerEntry":{"type":"object","required":["sequence","event_id","event_type","occurred_at","recorded_at","actor","event_hash","signatures"],"properties":{"sequence":{"type":"integer"},"event_id":{"type":"string","format":"uuid"},"idempotency_key":{"type":["string","null"]},"ledger_version":{"type":"string"},"event_type":{"type":"string"},"submission_id":{"type":["string","null"],"format":"uuid"},"submission_version_hash":{"type":["string","null"]},"claim_family_id":{"type":["string","null"]},"occurred_at":{"type":"string","description":"The engine canonical string, verbatim. Reformatting it breaks the event hash."},"recorded_at":{"type":"string"},"actor":{"type":"object"},"subject_refs":{"type":"object"},"payload":{"type":"object"},"evidence_refs":{"type":"array"},"supersedes_event_id":{"type":["string","null"],"format":"uuid"},"previous_event_hash":{"type":["string","null"]},"request_fingerprint":{"type":"string"},"event_hash":{"type":"string"},"signatures":{"type":"array","items":{"$ref":"#\/components\/schemas\/LedgerSignature"}}}},"LedgerList":{"allOf":[{"$ref":"#\/components\/schemas\/ContractEnvelope"},{"type":"object","required":["data","count","head","verification"],"properties":{"data":{"type":"array","items":{"$ref":"#\/components\/schemas\/LedgerEntry"}},"count":{"type":"integer"},"head":{"type":["string","null"]},"ledger_id":{"type":"string"},"verification":{"$ref":"#\/components\/schemas\/ChainVerification"},"public_keys":{"type":"array","items":{"$ref":"#\/components\/schemas\/PublicKey"}},"checkpoints":{"type":"array","items":{"type":"object"}},"custody_note":{"type":"string"}}}]},"ChainVerification":{"type":"object","required":["valid","event_count","head","failures","describe"],"properties":{"valid":{"type":"boolean"},"event_count":{"type":"integer"},"head":{"type":["string","null"]},"signatures_checked":{"type":"integer"},"failures":{"type":"array","items":{"type":"object"}},"describe":{"type":"string"}}},"PublicKey":{"type":"object","required":["key_id","algorithm","public_key_hex","controlled_by_publisher"],"properties":{"key_id":{"type":"string"},"algorithm":{"type":"string"},"public_key_hex":{"type":"string"},"signer":{"type":"string"},"organisation":{"type":"string"},"role":{"type":"string"},"controlled_by_publisher":{"type":"boolean"},"last_checkpoint_sequence":{"type":"integer"},"last_checkpoint_at":{"type":["string","null"],"format":"date-time"}}},"LedgerProof":{"allOf":[{"$ref":"#\/components\/schemas\/ContractEnvelope"},{"type":"object","required":["ledger_id","chain","checkpoint","checkpoint_verification"],"properties":{"ledger_id":{"type":"string"},"generated_at":{"type":"string","format":"date-time"},"chain":{"$ref":"#\/components\/schemas\/ChainVerification"},"checkpoint":{"type":["object","null"],"properties":{"sequence":{"type":"integer"},"chain_head":{"type":"string"},"event_count":{"type":"integer"},"checkpoint_date":{"type":["string","null"]},"publisher_key_id":{"type":"string"},"publisher_signature":{"$ref":"#\/components\/schemas\/LedgerSignature"},"witness_signatures":{"type":"array","items":{"$ref":"#\/components\/schemas\/LedgerSignature"}},"witnesses":{"type":"array","items":{"type":"string"}},"describe":{"type":["string","null"]}}},"checkpoint_verification":{"type":"object","properties":{"signatures_valid":{"type":"boolean"},"matches_current_head":{"type":["boolean","null"]},"live_head":{"type":["string","null"]},"required_witnesses":{"type":"integer"},"discrepancies":{"type":"array"},"statement":{"type":"string"}}},"public_keys":{"type":"array","items":{"$ref":"#\/components\/schemas\/PublicKey"}}}}]},"NoVerdict":{"allOf":[{"$ref":"#\/components\/schemas\/ContractEnvelope"},{"type":"object","required":["error","message","submission_id"],"properties":{"error":{"type":"string","examples":["no_adjudicated_verdict"]},"message":{"type":"string"},"submission_id":{"type":"string","format":"uuid"},"state":{"type":"string"},"engine_version":{"type":"string"}}}]},"NotFound":{"type":"object","properties":{"message":{"type":"string"}}}},"responses":{"NotFound":{"description":"No such record.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NotFound"}}}},"NoVerdict":{"description":"No adjudicated verdict exists for this receipt.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/NoVerdict"}}}}}}}