Getting started with Litmus
Litmus guides you through each step inside the product. This page lists what to have ready before you add your system, and the technical details for whoever connects it. For what Litmus does and whether it suits your system, see the Litmus page.
What you need
- A TechPass account for each person on your team who will sign in to Litmus. MOE staff without TechPass may sign in with their Google Workspace account instead.
- Details about your system: its name, a short description of what it does, the risks you are concerned about, the agency that owns it, and whether it is low or high risk. Litmus can help you draft the description and suggest risks.
- An endpoint Litmus can call: an HTTPS API endpoint for your system that can be reached from the internet, plus any key or token it needs. Litmus must connect to it successfully before you can finish adding the system. Connecting your system has the technical details.
- The right people. Someone who knows your system's API, to connect it. If an engineer will connect it, add them to the system in Litmus first. You add teammates by email and give each one an admin, editor or viewer role. Litmus doesn't send email notifications, so let people know when you've added them.
- Reference documents (optional): PDF, DOCX, TXT or Markdown files that test cases can draw on, such as the policy your system answers questions about. Litmus keeps the extracted text, not the original file.
- Your own test cases (optional): a CSV file of test cases you already have, using Litmus's template. Files can be up to 20 MB.
Connecting your system
For whoever connects your system: how Litmus calls its API.
| Setting | What Litmus does |
|---|---|
| Address | Calls an https:// URL that resolves to a public IP address, from Amazon Web Services in the Singapore region. |
| Method | Sends POST, with a JSON body. Only the test case changes from one call to the next. |
| Authentication | Signs requests with HMAC (Litmus generates the signing secret), or sends a bearer token, an API key in a header you name, or nothing. You can add other headers too. The token or key you enter in the authentication settings is stored encrypted, but other headers may not be, so put secrets in the authentication settings. |
| Request and reply | Fills in the request body template you set, replacing "{{testcase}}" with each test case. The placeholder must be a whole JSON string value, not part of a longer string. Reads the answer from the path you set in your system's JSON reply. There are presets for OpenAI and Azure OpenAI, Anthropic, Gemini and simple formats. |
| Timing | Waits up to 10 seconds for the answer. If your system needs longer, it can reply 202 Accepted straight away and, within 5 minutes, post {"job_id": …, "answer": …} to the callback URL Litmus sends with each request, signed with HMAC. |
| Errors | Tries again after a timeout, a 5xx reply or a failed connection, up to 3 attempts in all. Slows down if your system replies 429. Any other 4xx marks that test case as an error. A content filter's block, or a firewall's 403 page, counts as your system refusing, so make sure no firewall blocks Litmus. Troubleshooting has the details. |
| Load | Sends up to 5 requests a second, with short bursts of up to 10. You can set a lower limit, so it doesn't send requests faster than your system can handle. |
To be confirmed: the IP addresses Litmus calls from, for teams whose firewall must allow them.
Start
Sign in to Litmus (opens in a new tab) with TechPass, or Google if you're at MOE or GovTech, and add your system. The Litmus glossary (opens in a new tab) explains the terms Litmus uses.
Not sure whether your system fits, or stuck? Ask us using the onboarding form (opens in a new tab).