CINXE.COM

<!DOCTYPE html><html lang="en"> <head><meta charset="utf-8"><link rel="icon" type="image/svg+xml" href="/favicon.svg"><link rel="preload" as="image" href="/favicon.svg"><meta name="viewport" content="width=device-width"><meta name="generator" content="Astro v4.16.7"><meta property="og:url" content="https://pathoplexus.org/api-documentation"><meta property="og:title" content="Pathoplexus | API Documentation"><meta property="twitter:url" content="https://pathoplexus.org/api-documentation"><meta property="twitter:title" content="Pathoplexus | API Documentation"><title>API Documentation | Pathoplexus</title><script defer data-domain="pathoplexus.org" src="https://plausible.io/js/script.file-downloads.hash.outbound-links.js"></script><script>window.plausible = window.plausible || function() { (window.plausible.q = window.plausible.q || []).push(arguments) }</script><meta property="og:type" content="website" /><meta property="og:image" content="https://pathoplexus.org/images/pathoplexus-preview.png" /><meta property="og:description" content="Pathoplexus is a new, open-source database dedicated to the efficient sharing of human viral pathogen genomic data, fostering global collaboration and public health response." /><link rel="stylesheet" href="/_astro/index.D6vbhmQH.css"> <link rel="stylesheet" href="/_astro/index.BBas0nkL.css"></head> <body> <style>astro-island,astro-slot,astro-static-slot{display:contents}</style><script>(()=>{var e=async t=>{await(await t())()};(self.Astro||(self.Astro={})).load=e;window.dispatchEvent(new Event("astro:load"));})();;(()=>{var A=Object.defineProperty;var g=(i,o,a)=>o in i?A(i,o,{enumerable:!0,configurable:!0,writable:!0,value:a}):i[o]=a;var d=(i,o,a)=>g(i,typeof o!="symbol"?o+"":o,a);{let i={0:t=>m(t),1:t=>a(t),2:t=>new RegExp(t),3:t=>new Date(t),4:t=>new Map(a(t)),5:t=>new Set(a(t)),6:t=>BigInt(t),7:t=>new URL(t),8:t=>new Uint8Array(t),9:t=>new Uint16Array(t),10:t=>new Uint32Array(t),11:t=>1/0*t},o=t=>{let[l,e]=t;return l in i?i[l](e):void 0},a=t=>t.map(o),m=t=>typeof t!="object"||t===null?t:Object.fromEntries(Object.entries(t).map(([l,e])=>[l,o(e)]));class y extends HTMLElement{constructor(){super(...arguments);d(this,"Component");d(this,"hydrator");d(this,"hydrate",async()=>{var b;if(!this.hydrator||!this.isConnected)return;let e=(b=this.parentElement)==null?void 0:b.closest("astro-island[ssr]");if(e){e.addEventListener("astro:hydrate",this.hydrate,{once:!0});return}let c=this.querySelectorAll("astro-slot"),n={},h=this.querySelectorAll("template[data-astro-template]");for(let r of h){let s=r.closest(this.tagName);s!=null&&s.isSameNode(this)&&(n[r.getAttribute("data-astro-template")||"default"]=r.innerHTML,r.remove())}for(let r of c){let s=r.closest(this.tagName);s!=null&&s.isSameNode(this)&&(n[r.getAttribute("name")||"default"]=r.innerHTML)}let p;try{p=this.hasAttribute("props")?m(JSON.parse(this.getAttribute("props"))):{}}catch(r){let s=this.getAttribute("component-url")||"<unknown>",v=this.getAttribute("component-export");throw v&&(s+=` (export ${v})`),console.error(`[hydrate] Error parsing props for component ${s}`,this.getAttribute("props"),r),r}let u;await this.hydrator(this)(this.Component,p,n,{client:this.getAttribute("client")}),this.removeAttribute("ssr"),this.dispatchEvent(new CustomEvent("astro:hydrate"))});d(this,"unmount",()=>{this.isConnected||this.dispatchEvent(new CustomEvent("astro:unmount"))})}disconnectedCallback(){document.removeEventListener("astro:after-swap",this.unmount),document.addEventListener("astro:after-swap",this.unmount,{once:!0})}connectedCallback(){if(!this.hasAttribute("await-children")||document.readyState==="interactive"||document.readyState==="complete")this.childrenConnectedCallback();else{let e=()=>{document.removeEventListener("DOMContentLoaded",e),c.disconnect(),this.childrenConnectedCallback()},c=new MutationObserver(()=>{var n;((n=this.lastChild)==null?void 0:n.nodeType)===Node.COMMENT_NODE&&this.lastChild.nodeValue==="astro:end"&&(this.lastChild.remove(),e())});c.observe(this,{childList:!0}),document.addEventListener("DOMContentLoaded",e)}}async childrenConnectedCallback(){let e=this.getAttribute("before-hydration-url");e&&await import(e),this.start()}async start(){let e=JSON.parse(this.getAttribute("opts")),c=this.getAttribute("client");if(Astro[c]===void 0){window.addEventListener(`astro:${c}`,()=>this.start(),{once:!0});return}try{await Astro[c](async()=>{let n=this.getAttribute("renderer-url"),[h,{default:p}]=await Promise.all([import(this.getAttribute("component-url")),n?import(n):()=>()=>{}]),u=this.getAttribute("component-export")||"default";if(!u.includes("."))this.Component=h[u];else{this.Component=h;for(let f of u.split("."))this.Component=this.Component[f]}return this.hydrator=p,this.hydrate},e,this)}catch(n){console.error(`[astro-island] Error hydrating ${this.getAttribute("component-url")}`,n)}}attributeChangedCallback(){this.hydrate()}}d(y,"observedAttributes",["props"]),customElements.get("astro-island")||customElements.define("astro-island",y)}})();</script><astro-island uid="fU3Jc" prefix="r0" component-url="/_astro/Banner._VYySrz3.js" component-export="Banner" renderer-url="/_astro/client.CManSo_T.js" props="{"message":[0],"lastTimeBannerWasClosed":[0],"serverTime":[0,1732710834929]}" ssr="" client="load" opts="{"name":"Banner","value":true}"></astro-island> <div class="flex flex-col min-h-screen w-11/12 mx-auto"> <astro-island uid="ZW749X" prefix="r1" component-url="/_astro/_astro-entry_react-toastify.BtmXnCde.js" component-export="ToastContainer" renderer-url="/_astro/client.CManSo_T.js" props="{}" ssr="" client="load" opts="{"name":"ToastContainer","value":true}" await-children=""><div class="Toastify"></div></astro-island> <header class="bg-white h-fit z-30"> <nav class="flex justify-between items-center p-4"> <div class="flex justify-start"> <div class="flex flex-col"> <div class="flex flex-row pb-3"> <a href="/"><img class="h-8 mr-4" src="/favicon.svg" alt="icon" style="aspect-ratio:100/100"></a> <a href="/" class="fancytitle mr-4">Pathoplexus</a> </div> <div class="dropdown dropdown-hover flex relative"> <label tabindex="0" class="py-1 block text-primary-1500 cursor-pointer"> Organisms <span class="text-primary"> <svg viewBox="0 0 40 40" width="1.2em" height="1.2em" class="inline-block -mt-1 ml-1 h-4 w-4"><path fill="currentColor" d="M4.659 11.833h30.682L20 32.167z"></path></svg></span> </label> <ul tabindex="0" class="dropdown-content z-20 menu p-1 shadow bg-base-100 rounded-btn absolute top-full -left-4"> <li> <a href="/cchf" class="text-primary-1500"> Crimean-Congo Hemorrhagic Fever Virus </a> </li><li> <a href="/ebola-sudan" class="text-primary-1500"> Ebola Sudan </a> </li><li> <a href="/ebola-zaire" class="text-primary-1500"> Ebola Zaire </a> </li><li> <a href="/west-nile" class="text-primary-1500"> West Nile Virus </a> </li> </ul> </div> </div> </div> <div class="flex justify-end relative"> <div class="subtitle hidden md:flex md:z-6 gap-4"> <a href="/organism-selector/search">Browse</a><a href="/organism-selector/submission">Submit</a><a href="/seqsets">SeqSets</a><a href="/news">News</a><a href="/about">About</a><a href="/docs/">Docs</a><a href="https://authentication.pathoplexus.org/realms/loculus/protocol/openid-connect/auth?client_id=backend-client&scope=openid&response_type=code&redirect_uri=https%3A%2F%2Fpathoplexus.org%2Fapi-documentation">Login</a> </div> <div class="md:hidden z-0" style="position:absolute;right:1.5rem;top:-2rem"> <astro-island uid="Z2faBmx" prefix="r3" component-url="/_astro/SandwichMenu.Dx3CfgfB.js" component-export="SandwichMenu" renderer-url="/_astro/client.CManSo_T.js" props="{"topNavigationItems":[1,[[0,{"text":[0,"Browse"],"path":[0,"/organism-selector/search"]}],[0,{"text":[0,"Submit"],"path":[0,"/organism-selector/submission"]}],[0,{"text":[0,"SeqSets"],"path":[0,"/seqsets"]}],[0,{"text":[0,"News"],"path":[0,"/news"]}],[0,{"text":[0,"About"],"path":[0,"/about"]}],[0,{"text":[0,"Docs"],"path":[0,"/docs/"]}],[0,{"text":[0,"Login"],"path":[0,"https://authentication.pathoplexus.org/realms/loculus/protocol/openid-connect/auth?client_id=backend-client&scope=openid&response_type=code&redirect_uri=https%3A%2F%2Fpathoplexus.org%2Fapi-documentation"]}]]],"gitHubMainUrl":[0,"https://github.com/loculus-project/loculus"]}" ssr="" client="load" opts="{"name":"SandwichMenu","value":true}" await-children=""><div class="relative"><button class="absolute z-50 bg-transparent border-none cursor-pointer"><div class="relative" aria-label="main menu"><div class="hamburger"><div class="burger bg-primary-600 burger1--closed"></div><div class="burger bg-primary-600 burger2--closed"></div><div class="burger bg-primary-600 burger3--closed"></div></div><style> .hamburger { width: 2rem; height: 2rem; display: flex; justify-content: space-around; flex-flow: column nowrap; z-index: 1001; } .burger { width: 2rem; height: 0.25rem; border-radius: 10px; transform-origin: 1px; transition: all 0.3s linear; } .burger1--open { transform: rotate(45deg); } .burger1--closed { transform: rotate(0); } .burger2--open { opacity: 0; } .burger2--closed { opacity: 1; } .burger3--open { transform: rotate(-45deg); } .burger3--closed { transform: rotate(0); } </style></div></button><div class="fixed top-0 right-0 bg-white w-64 min-h-screen flex flex-col offCanvasTransform translate-x-full"><button class="absolute z-50 bg-transparent border-none cursor-pointer right-3 top-4"><div class="relative" aria-label="main menu"><div class="hamburger"><div class="burger bg-primary-600 burger1--closed"></div><div class="burger bg-primary-600 burger2--closed"></div><div class="burger bg-primary-600 burger3--closed"></div></div><style> .hamburger { width: 2rem; height: 2rem; display: flex; justify-content: space-around; flex-flow: column nowrap; z-index: 1001; } .burger { width: 2rem; height: 0.25rem; border-radius: 10px; transform-origin: 1px; transition: all 0.3s linear; } .burger1--open { transform: rotate(45deg); } .burger1--closed { transform: rotate(0); } .burger2--open { opacity: 0; } .burger2--closed { opacity: 1; } .burger3--open { transform: rotate(-45deg); } .burger3--closed { transform: rotate(0); } </style></div></button><div class="font-bold p-5 flex flex-col justify-between min-h-screen max-h-screen overflow-y-auto"><div><div class="h-10"><a href="/">Loculus</a></div><div class="flex-grow divide-y-2 divide-gray-300 divide-solid border-t-2 border-b-2 border-gray-300 border-solid "><div><div class="flex items-center"><div class="ml-4 py-3"><a href="/organism-selector/search"> Browse</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-3"><a href="/organism-selector/submission"> Submit</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-3"><a href="/seqsets"> SeqSets</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-3"><a href="/news"> News</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-3"><a href="/about"> About</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-3"><a href="/docs/"> Docs</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-3"><a href="https://authentication.pathoplexus.org/realms/loculus/protocol/openid-connect/auth?client_id=backend-client&scope=openid&response_type=code&redirect_uri=https%3A%2F%2Fpathoplexus.org%2Fapi-documentation"> Login</a></div></div></div></div></div><div class="mt-auto mb-10"><div class="flex justify-end items-center py-5"><a href="https://github.com/loculus-project/loculus"><img src="/github-mark.svg" class="w-8" alt="GitHub logo"/></a></div><div class="font-light divide-y-2 divide-gray-300 divide-solid border-t-2 border-b-2 border-gray-300 border-solid "><div><div class="flex items-center"><div class="ml-4 py-1"><a href="/api-documentation"> API docs</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-1"><a href="/about/governance"> Governance</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-1"><a href="/contact"> Contact</a></div></div></div><div><div class="flex items-center"><div class="ml-4 py-1"><a href="https://status.pathoplexus.org/"> Status</a></div></div></div></div></div></div></div></div></astro-island> </div> </div> </nav> <hr class="border-t border-gray-1000"> </header> <div class="flex-grow mt-3 mb-5 px-4"> <div class="container mx-auto p-8"> <h1 class="title">API Documentation</h1> <div> <p class="mt-4 mb-4"> There is a <a href="https://swagger.io/tools/swagger-ui/" class="underline text-primary-900 hover:text-primary-800 hover:no-underline"> Swagger UI </a> for documentation and direct interaction with the APIs. For more tips on how to use the API, it is recommended to start with the <a href="/docs/how-to/authentication-api" class="underline text-primary-900 hover:text-primary-800 hover:no-underline"> API Authentication documentation. </a> </p> <p class="mt-4 mb-4"> WARNING: Swagger incorrectly displays NDJSON examples in JSON format. For endpoints that require NDJSON as input you must convert the JSON examples to NDJSON (e.g. by removing new lines) prior to testing. </p> <p class="mt-4 mb-4"> By using our API you agree to our <a href="/about/terms-of-use/data-use-terms" class="underline text-primary-900 hover:text-primary-800 hover:no-underline"> Data Use Terms </a>. </p> </div> <div class="mb-8 mt-10"> <h2 class="text-xl font-semibold text-primary-400 mb-4">Backend Server</h2> <div class="mb-4"> Please note that Loculus is under continuous development and the endpoints are subject to change. </div> <a class="inline-block px-6 py-3 bg-primary-400 text-white font-semibold rounded-lg shadow-md hover:bg-primary-500 mr-2 hover:no-underline" href="https://backend.pathoplexus.org/swagger-ui/index.html"> View Backend API Documentation </a> </div> <div> <h2 class="text-xl font-semibold text-primary-400 mb-4">LAPIS Query Engines</h2> <div class="space-y-4"> <a class="inline-block px-6 py-3 bg-primary-400 text-white font-semibold rounded-lg shadow-md hover:bg-primary-500 mr-2 hover:no-underline" href="https://lapis.pathoplexus.org/cchf/swagger-ui/index.html"> Crimean-Congo Hemorrhagic Fever Virus LAPIS API Documentation </a><a class="inline-block px-6 py-3 bg-primary-400 text-white font-semibold rounded-lg shadow-md hover:bg-primary-500 mr-2 hover:no-underline" href="https://lapis.pathoplexus.org/ebola-sudan/swagger-ui/index.html"> Ebola Sudan LAPIS API Documentation </a><a class="inline-block px-6 py-3 bg-primary-400 text-white font-semibold rounded-lg shadow-md hover:bg-primary-500 mr-2 hover:no-underline" href="https://lapis.pathoplexus.org/ebola-zaire/swagger-ui/index.html"> Ebola Zaire LAPIS API Documentation </a><a class="inline-block px-6 py-3 bg-primary-400 text-white font-semibold rounded-lg shadow-md hover:bg-primary-500 mr-2 hover:no-underline" href="https://lapis.pathoplexus.org/west-nile/swagger-ui/index.html"> West Nile Virus LAPIS API Documentation </a> </div> </div> </div> </div> <hr class="border-t border-gray-1000"> <footer class="hidden sm:flex sm:z-6 sm:z-6 flex justify-between items-center h-20"> <div class="flex gap-5"> <a href="/api-documentation" class="text-gray-600"> API docs </a><a href="/about/governance" class="text-gray-600"> Governance </a><a href="/contact" class="text-gray-600"> Contact </a><a href="https://status.pathoplexus.org/" class="text-gray-600"> Status </a> </div> <a href="https://github.com/loculus-project/loculus" class="h-full py-6"> <img src="/github-mark.svg" class="h-full object-scale-down" alt="github-icon"> </a> </footer> </div> </body></html>