Developers
Search and order through the API or an AI agent
The same flow as the website for your own tools, LIMS or AI agents: find labs, send them a request, get quotes, accept one, and collect results. JSON over HTTPS, an OpenAPI 3.1 description, and an MCP server for agents. Searching needs no key.
Quick start
Base URL https://midgardscience.aramous.com. Search first; it needs no key. Then get a key by email and create a request. Every call and its answer is in the API reference.
# 1. Search: no key needed
curl -X POST https://midgardscience.aramous.com/api/v1/search \
-H "Content-Type: application/json" \
-d '{"query":"Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis","limit":3}'
# 2. Get a key: a code by email, then trade it
curl -X POST https://midgardscience.aramous.com/api/v1/auth/code \
-H "Content-Type: application/json" \
-d '{"email": "you@company.com"}'
curl -X POST https://midgardscience.aramous.com/api/v1/auth/token \
-H "Content-Type: application/json" \
-d '{"email": "you@company.com", "code": "123456", "label": "curl"}'
KEY=mg_... # the "key" from the answer, shown once
# 3. Create a request. Nothing is sent to suppliers yet
curl -X POST https://midgardscience.aramous.com/api/v1/requests \
-H "Authorization: Bearer $KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{"site":"science","category":"assays","title":"IC50 for 40 compounds in a kinase assay","spec":{"assay":"IC50 against a 10-kinase panel","sample_type":"small molecules in DMSO","replicates":"Triplicate","controls":"vehicle and staurosporine on every plate"},"quantity":40,"needed_by":"2027-01-15"}'
# 4. See its suggestions, then ask the suppliers you pick
curl https://midgardscience.aramous.com/api/v1/requests/req_... -H "Authorization: Bearer $KEY"
curl -X POST https://midgardscience.aramous.com/api/v1/requests/req_.../actions \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"action": "confirm_labs", "supplierIds": ["sup_..."]}'Python
One file, standard library only. Save it as midgard.py and run python3 midgard.py to search, or import it.
midgard.py
"""midgard.py: a client for the Midgard API in one file, standard library only (Python 3.9+).
Run it to search: python3 midgard.py
Use it from code: from midgard import Midgard
"""
import json
import sys
import urllib.error
import urllib.parse
import urllib.request
BASE = "https://midgardscience.aramous.com"
class MidgardError(Exception):
def __init__(self, status, code, message):
super().__init__(f"{status} {code}: {message}")
self.status, self.code, self.message = status, code, message
class Midgard:
def __init__(self, base=BASE, key=None):
self.base, self.key = base.rstrip("/"), key
def call(self, method, path, body=None, headers=None):
h = {"Accept": "application/json", **(headers or {})}
data = None
if body is not None:
data = json.dumps(body).encode()
h["Content-Type"] = "application/json"
if self.key:
h["Authorization"] = f"Bearer {self.key}"
req = urllib.request.Request(self.base + path, data=data, method=method, headers=h)
try:
with urllib.request.urlopen(req, timeout=120) as res:
return json.loads(res.read() or b"null")
except urllib.error.HTTPError as e:
err = (json.loads(e.read() or b"{}") or {}).get("error") or {}
raise MidgardError(e.code, err.get("code", "error"), err.get("message", e.reason)) from None
# No key needed
def search(self, query, **opts):
"""Plain-language search: ranked suppliers with reasons, and a request draft."""
return self.call("POST", "/api/v1/search", {"query": query, **opts})
def suppliers(self, **params):
return self.call("GET", "/api/v1/suppliers?" + urllib.parse.urlencode(params))
def supplier(self, slug):
return self.call("GET", "/api/v1/suppliers/" + urllib.parse.quote(slug))
def categories(self):
return self.call("GET", "/api/v1/categories")
# Sign in: a code by email, then a key
def send_code(self, email):
return self.call("POST", "/api/v1/auth/code", {"email": email})
def sign_in(self, email, code, label="midgard.py"):
out = self.call("POST", "/api/v1/auth/token", {"email": email, "code": code, "label": label})
self.key = out["key"]
return out
# With a key
def create_request(self, request, idempotency_key=None):
headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
return self.call("POST", "/api/v1/requests", request, headers)
def requests(self, **params):
return self.call("GET", "/api/v1/requests?" + urllib.parse.urlencode(params))
def request(self, request_id):
return self.call("GET", "/api/v1/requests/" + request_id)
def act(self, request_id, action, **fields):
return self.call("POST", f"/api/v1/requests/{request_id}/actions", {"action": action, **fields})
def accept_quote(self, quote_id, **choice):
return self.call("POST", f"/api/v1/quotes/{quote_id}/accept", choice)
def cancel(self, request_id, reason=None, outcome_reason=None):
body = {k: v for k, v in {"reason": reason, "outcome_reason": outcome_reason}.items() if v}
return self.call("POST", f"/api/v1/requests/{request_id}/cancel", body)
if __name__ == "__main__":
query = " ".join(sys.argv[1:]) or "Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis"
found = Midgard().search(query, limit=3)
for s in found["suppliers"]:
print(f"{s['name']} ({s['fit']}): {s['url']}")
for reason in s["reasons"]:
print(" -", reason)
print("Still needed:", [m["question"] for m in found["missing"]])
import uuid
from midgard import Midgard
m = Midgard()
m.send_code("you@company.com")
m.sign_in("you@company.com", input("Code from the email: "))
found = m.search("Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis")
draft = found["request_draft"]
# Check the draft with the person, and ask them each detail the search could not fill.
# A blank answer lets the suppliers say what they would use, where that is allowed.
for q in found["missing"]:
answer = input(q["question"] + " ").strip()
while not answer and not q["not_known_allowed"]:
answer = input(q["question"] + " (needed) ").strip()
if answer:
draft["spec"][q["key"]] = answer
else:
draft["spec_unknown"].append(q["key"])
# draft["suppliers"] holds the suppliers the search found. Creating the request asks no one;
# keep the ones the person picks and ask them with confirm_labs below.
picked = draft.pop("suppliers")
# A new idempotency key for each request; send the same one again only to retry this one.
req = m.create_request(draft, idempotency_key=str(uuid.uuid4()))
print(req["status_url"])
# Nothing has gone to suppliers yet. Ask the ones the person picks:
m.act(req["id"], "confirm_labs", slugs=picked[:3])TypeScript
One file, no dependencies. Save it as midgard.ts and run node midgard.ts (Node 22.18 or later), deno run --allow-net midgard.ts or bun midgard.ts.
midgard.ts
// midgard.ts: a client for the Midgard API in one file, no dependencies.
// Node 22.18 or later runs it as is (node midgard.ts); so do Deno and Bun.
const BASE = "https://midgardscience.aramous.com";
export class MidgardError extends Error {
status: number;
code: string;
constructor(status: number, code: string, message: string) {
super(`${status} ${code}: ${message}`);
this.status = status;
this.code = code;
}
}
type Json = Record<string, any>;
type OutcomeReason = "price" | "lead_time" | "capability" | "other";
export class Midgard {
base: string;
key?: string;
constructor(base: string = BASE, key?: string) {
this.base = base.replace(/\/+$/, "");
this.key = key;
}
async call(method: string, path: string, body?: unknown, headers: Record<string, string> = {}): Promise<Json> {
const h: Record<string, string> = { Accept: "application/json", ...headers };
if (body !== undefined) h["Content-Type"] = "application/json";
if (this.key) h.Authorization = `Bearer ${this.key}`;
const res = await fetch(this.base + path, { method, headers: h, body: body === undefined ? undefined : JSON.stringify(body) });
const out = await res.json().catch(() => ({}));
if (!res.ok) throw new MidgardError(res.status, out?.error?.code ?? "error", out?.error?.message ?? res.statusText);
return out;
}
// No key needed
search(query: string, opts: { site?: string; category?: string; region?: string; standard?: string; limit?: number } = {}) {
return this.call("POST", "/api/v1/search", { query, ...opts });
}
suppliers(params: Record<string, string> = {}) {
return this.call("GET", "/api/v1/suppliers?" + new URLSearchParams(params));
}
supplier(slug: string) {
return this.call("GET", "/api/v1/suppliers/" + encodeURIComponent(slug));
}
categories() {
return this.call("GET", "/api/v1/categories");
}
// Sign in: a code by email, then a key
sendCode(email: string) {
return this.call("POST", "/api/v1/auth/code", { email });
}
async signIn(email: string, code: string, label = "midgard.ts") {
const out = await this.call("POST", "/api/v1/auth/token", { email, code, label });
this.key = out.key;
return out;
}
// With a key
createRequest(request: Json, idempotencyKey?: string) {
return this.call("POST", "/api/v1/requests", request, idempotencyKey ? { "Idempotency-Key": idempotencyKey } : {});
}
requests(params: Record<string, string> = {}) {
return this.call("GET", "/api/v1/requests?" + new URLSearchParams(params));
}
request(id: string) {
return this.call("GET", `/api/v1/requests/${id}`);
}
act(id: string, action: string, fields: Json = {}) {
return this.call("POST", `/api/v1/requests/${id}/actions`, { action, ...fields });
}
acceptQuote(quoteId: string, choice: { continue: "midgard" | "own"; terms_name?: string; po?: string; billing_email?: string; revision?: string; outcome_reason?: OutcomeReason }) {
return this.call("POST", `/api/v1/quotes/${quoteId}/accept`, choice);
}
cancel(id: string, reason?: string, outcomeReason?: OutcomeReason) {
return this.call("POST", `/api/v1/requests/${id}/cancel`, { ...(reason ? { reason } : {}), ...(outcomeReason ? { outcome_reason: outcomeReason } : {}) });
}
}
// Run directly: search and print the suppliers that fit.
if (process.argv[1]?.endsWith("midgard.ts")) {
const query = process.argv.slice(2).join(" ") || "Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis";
const found = await new Midgard().search(query, { limit: 3 });
for (const s of found.suppliers) {
console.log(`${s.name} (${s.fit}): ${s.url}`);
for (const r of s.reasons) console.log(" -", r);
}
console.log("Still needed:", found.missing.map((m: Json) => m.question));
}
Add to Claude Code, Cursor or any MCP client
The API is also an MCP server, over Streamable HTTP. An agent can search without signing in. To order, it signs in inside the conversation: it asks for your email, you read it the code from the email, and the connection is signed in without the key ever appearing in the chat.
- Midgard Science: https://midgardscience.aramous.com/api/mcp
- Midgard Industrial: https://midgardindustrial.aramous.com/api/mcp
claude mcp add --transport http midgard-science https://midgardscience.aramous.com/api/mcp claude mcp add --transport http midgard-industrial https://midgardindustrial.aramous.com/api/mcp # Or with a key, so there is nothing to sign in to claude mcp add --transport http midgard-science https://midgardscience.aramous.com/api/mcp \ --header "Authorization: Bearer mg_..."
{
"mcpServers": {
"midgard-science": {
"url": "https://midgardscience.aramous.com/api/mcp"
}
}
}{
"servers": {
"midgard-science": {
"type": "http",
"url": "https://midgardscience.aramous.com/api/mcp"
}
}
}{
"mcpServers": {
"midgard-science": {
"type": "http",
"url": "https://midgardscience.aramous.com/api/mcp"
}
}
}{
"mcpServers": {
"midgard-science": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://midgardscience.aramous.com/api/mcp"
]
}
}
}npx @modelcontextprotocol/inspector --cli https://midgardscience.aramous.com/api/mcp --transport http --method tools/list
16 tools: 8 read-only, the rest marked with what they change, so a client can ask before running them. The agent asks you for your name before accepting order terms, and gives you the payment link to open; it cannot pay. Every tool, its arguments and errors.
From request to order
GET /api/v1/requests/{id} lists suggestions: each lab with its supplier_id, name and reasons. Nothing is sent until you confirm who gets it with confirm_labs, or name them in suppliers when you create the request.
When status is quoted, quotes holds each lab's itemised quote, and each quote's ways lists how you can continue with it. continue is required: "midgard" keeps the order on Midgard under the order terms, accepted by the person named in terms_name; "own" takes the quote to the lab directly.
curl -X POST https://midgardscience.aramous.com/api/v1/quotes/qt_.../accept \
-H "Authorization: Bearer $KEY" \
-H "Content-Type: application/json" \
-d '{"continue": "midgard", "terms_name": "Ada Lovelace", "po": "4500012345"}'{"action":"confirm_labs","supplierIds":["sup_..."]}Send the quote request to these suppliers (ids from suggestions, or "slugs" from a search). Status goes from new to sourcing.{"action":"answer_question","rfqId":"rfq_...","answer":"..."}Answer a supplier's question.{"action":"choose_managed","quoteId":"qt_...","termsName":"Ada Lovelace","po":"4500012345"}Keep the order here under the order terms. Without a PO the reply carries paymentUrl for the first card payment.{"action":"choose_direct","quoteId":"qt_..."}Deal with the supplier on your own. The timeline then carries their contact details.{"action":"decide_change","changeId":"co_...","approve":true}Approve or decline a change the supplier proposed.{"action":"pay","paymentId":"pay_..."}A card payment link for an instalment that is due.{"action":"accept_results"}Accept what was delivered.{"action":"request_rerun","reason":"..."}Raise an issue with what was delivered.
All of these are POST /api/v1/requests/{id}/actions. Statuses: new → sourcing → quoted → accepted → paid → in_progress → delivered. Poll GET /api/v1/requests/{id}/events?since=, or set a webhook: callbacks are signed with HMAC-SHA256 in a Webhook-Signature header.
Endpoints
Errors are {"error": {"code", "message"}} with an HTTP status. With a key, 120 calls a minute; each answer carries RateLimit-Remaining and RateLimit-Reset. Each endpoint with an example call, its answer, its errors and limits:
- POST/api/v1/searchFind suppliers for work described in plain words
- GET/api/v1/suppliersSearch and page through the directory
- GET/api/v1/suppliers/{slug}One supplier
- GET/api/v1/categoriesSites, categories and request fields
- POST/api/v1/auth/codeEmail a sign-in code
- POST/api/v1/auth/tokenTrade the code for a key
- GET/api/v1/meWho the key acts for
- GET/api/v1/keysList keys
- DELETE/api/v1/keys/{id}Revoke a key
- POST/api/v1/uploadsUpload a file
- POST/api/v1/requestsCreate a request
- GET/api/v1/requestsList your requests
- GET/api/v1/requests/{id}One request
- GET/api/v1/requests/{id}/eventsThe timeline
- GET/api/v1/requests/{id}/messagesRead the messages
- POST/api/v1/requests/{id}/messagesSend a message
- POST/api/v1/requests/{id}/actionsAct on a request
- POST/api/v1/quotes/{id}/acceptAccept a quote
- POST/api/v1/requests/{id}/cancelCancel a request
- GET/api/v1/webhookRead the webhook address
- PUT/api/v1/webhookSet the webhook address
- DELETE/api/v1/webhookStop callbacks
- GET/api/v1/openapi.jsonOpenAPI description