Midgard Science

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.

curl
# 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"]])
Ordering with it
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 Code
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_..."
Cursor: ~/.cursor/mcp.json, or .cursor/mcp.json in a project
{
  "mcpServers": {
    "midgard-science": {
      "url": "https://midgardscience.aramous.com/api/mcp"
    }
  }
}
VS Code: .vscode/mcp.json
{
  "servers": {
    "midgard-science": {
      "type": "http",
      "url": "https://midgardscience.aramous.com/api/mcp"
    }
  }
}
Any client that speaks Streamable HTTP
{
  "mcpServers": {
    "midgard-science": {
      "type": "http",
      "url": "https://midgardscience.aramous.com/api/mcp"
    }
  }
}
A client that only runs local (stdio) servers, through the mcp-remote bridge
{
  "mcpServers": {
    "midgard-science": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://midgardscience.aramous.com/api/mcp"
      ]
    }
  }
}
Check the connection and list the tools
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: