# Midgard Science API

> Midgard Science passes requests for quotes to independent suppliers and relays their quotes, for lab work (Assays & in vitro testing, Protein production, ADME, DMPK & toxicology, Cell line development, Genomics & sequencing, CDMO: development & manufacturing); chemistry (Custom peptides, Compounds & building blocks). Search the directory, send a request, receive quotes, accept one and follow the order, over JSON or MCP.

Base URL: https://midgardscience.aramous.com. OpenAPI: https://midgardscience.aramous.com/api/v1/openapi.json. MCP: https://midgardscience.aramous.com/api/mcp. HTML version: https://midgardscience.aramous.com/developers.

Searching needs no key. To order, get a key by email: POST /api/v1/auth/code, then POST /api/v1/auth/token with the six-digit code. Send it as `Authorization: Bearer mg_...`. A key acts for its email and sees every request placed with that address, on the website too. Errors are `{"error": {"code", "message"}}` with an HTTP status.

The flow: search, create a request (status `new`; GET it for its `suggestions`), fill in what its `missing` lists (`set_spec`, or mark a field not known), confirm which suppliers to ask (`confirm_labs`, status `sourcing`), wait for `quoted` (poll or webhook), then accept a quote: keep the order on the site, or take it to the supplier directly. Statuses: new, sourcing, quoted, accepted, paid, in_progress, delivered, closed; also cancelled and introduced (continued directly with the supplier).

## Conventions

- Keys: Searching needs no key. To order: POST /api/v1/auth/code with `{"email"}`, then POST /api/v1/auth/token with `{"email", "code"}` from the email; send the `key` as `Authorization: Bearer mg_...`. A 401 says how to get or send one.
- Errors: `{"error": {"code", "message"}}` with an HTTP status. A 400 message starts with the field it is about, e.g. `quantity: ...`.
- Limits: With a key, 120 calls a minute across every keyed endpoint and the MCP server. Search: 10 an hour per network address without a key, 100 with one. Every answer from a limited endpoint carries `RateLimit-Limit` (calls the window allows), `RateLimit-Remaining` (calls left), `RateLimit-Reset` (seconds until a call is freed) and `RateLimit-Policy` (e.g. `120;w=60`). A 429 adds `Retry-After`, the seconds to wait.
- Paging: GET /api/v1/suppliers takes `page` and `per_page` and answers with `total`. GET /api/v1/requests takes `limit` and `starting_after` and answers with `has_more` and `next_starting_after`.
- Retries: POST /api/v1/requests takes an `Idempotency-Key` header: a new value for each request, the same value to retry it. A retry with the same body answers 200 with `Idempotent-Replayed: true`; the same value with any change to the body answers 409 `idempotency_conflict`. Cancelling twice answers the same.
- Files: Upload with POST /api/v1/uploads (multipart field `file`), or over MCP with the `upload_file` tool (base64 or an https address), then put the `url` in the category's spec field of `type: "file"`.

## Quick start: curl

```bash
# 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_..."]}'
```

## Quick start: Python

Save as `midgard.py` and run `python3 midgard.py`. Standard library only.

```python
"""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:

```python
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])
```

## Quick start: TypeScript

Save as `midgard.ts` and run `node midgard.ts` (Node 22.18 or later), `deno run --allow-net midgard.ts` or `bun midgard.ts`. No dependencies.

```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));
}

```

## Use from an AI agent (MCP)

The API is also an MCP server over Streamable HTTP. Searching needs no sign-in. To order, the agent signs in inside the conversation: `sign_in` emails the person a six-digit code, they read it out, and `verify_code` signs the connection in. Or connect with an API key in the `Authorization` header.

- Midgard Science: https://midgardscience.aramous.com/api/mcp
- Midgard Industrial: https://midgardindustrial.aramous.com/api/mcp

Claude Code:

```bash
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

# 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):

```json
{
  "mcpServers": {
    "midgard-science": {
      "url": "https://midgardscience.aramous.com/api/mcp"
    }
  }
}
```

VS Code (`.vscode/mcp.json`):

```json
{
  "servers": {
    "midgard-science": {
      "type": "http",
      "url": "https://midgardscience.aramous.com/api/mcp"
    }
  }
}
```

Any client that speaks Streamable HTTP:

```json
{
  "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:

```json
{
  "mcpServers": {
    "midgard-science": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://midgardscience.aramous.com/api/mcp"
      ]
    }
  }
}
```

Check the connection and list the tools:

```bash
npx @modelcontextprotocol/inspector --cli https://midgardscience.aramous.com/api/mcp --transport http --method tools/list
```

## Endpoints

### POST /api/v1/search

Find suppliers for work described in plain words. The work in plain language in, suppliers ranked by fit out, each with the reasons taken from its profile. The answer also carries `request_draft`, a body for POST /api/v1/requests, and `missing`, the details to ask about: one with `not_known_allowed: false` needs a value before the request is created; one with `true` needs a value, or its key in `spec_unknown`, before it goes to suppliers. A key is optional; sent, it must be valid.

Auth: optional `Authorization: Bearer mg_...`.
MCP tool: `find_suppliers`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `query` | body | string, 6 to 3000 characters | yes | The work: what, how many, standards, deadlines. |
| `site` | body | "science" \| "industrial" | no | Defaults to the site this address serves. |
| `category` | body | string | no | A category slug from GET /api/v1/categories. Leave it out to let the search choose. |
| `region` | body | "any" \| "na" \| "us" \| "eu" \| "india" \| "asia" | no | "eu" includes the UK. For a US state or a city, name it in `query` (e.g. "in Ohio"), or filter GET /api/v1/suppliers by `region`. |
| `standard` | body | string | no | Only suppliers whose listing names this standard, e.g. GLP or ISO 13485. |
| `limit` | body | integer 1 to 10 | no | Default 8. |

Example:

```bash
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}'
```

Response 200:

```json
{
  "object": "search_result",
  "query": "Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis",
  "site": "science",
  "category": "dmpk-tox",
  "summary": null,
  "ranked_by": "model",
  "scoped_by": "model",
  "searched": {
    "listings": 1771,
    "by_meaning": true
  },
  "suppliers": [
    {
      "slug": "example-lab",
      "name": "Example Lab",
      "location": {
        "city": "Boston",
        "region": "MA",
        "country": "US"
      },
      "website": "https://lab.example.com",
      "logo_url": null,
      "url": "https://midgardscience.aramous.com/s/example-lab",
      "fit": "strong",
      "reasons": [
        "Its profile lists this service."
      ],
      "standards": [
        "ISO 17025"
      ],
      "certifications": [
        "ISO 17025"
      ],
      "direct": {
        "kind": "form",
        "href": "https://lab.example.com/quote",
        "opens": "form"
      },
      "provider": null
    }
  ],
  "request_draft": {
    "site": "science",
    "category": "dmpk-tox",
    "title": "Mouse PK study with LC-MS/MS bioanalysis",
    "spec": {
      "study": "PK study (in vivo)",
      "compounds": "3 small-molecule compounds",
      "species": "Mouse",
      "glp": "Non-GLP"
    },
    "quantity": 3,
    "needed_by": null,
    "details": "Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis",
    "suppliers": [
      "example-lab"
    ],
    "spec_unknown": []
  },
  "missing": [
    {
      "key": "route",
      "question": "Route?",
      "options": [],
      "not_known_allowed": true
    }
  ],
  "questions": []
}
```

`fit` is `strong` when the listing states the work and every standard and place the query asks for, `possible` when it states part of it or the search fell back to keywords. `reasons` are taken from the listing; say only what they say. `certifications` is every standard the listing names, as a short tag (GET /api/v1/suppliers/{slug} gives each in the listing's own words under `quality`); `standards` is the part of it this site's departments show. `ranked_by` is `keywords` and `scoped_by` is `rules` when the model was not used. `searched` says how many listings were searched and whether by meaning. `request_draft.suppliers` holds the strong fits; `quantity` and `needed_by` are null when the query does not say.

Errors:

- 400 `invalid_json`: The body is not a JSON object.
- 400 `invalid_request`: query too short or too long; unknown site, category or region; limit out of range. The message names the field.
- 401 `unauthorized`: A key was sent and is not valid.
- 429 `rate_limited`: Over the hourly limit. The answer carries `Retry-After`, the seconds to wait.
- 500 `server_error`: The search failed; try again.

Limits: 10 searches an hour per network address without a key, 100 an hour with one. Only valid calls count. A search takes up to a minute.

### GET /api/v1/suppliers

Search and page through the directory. The website's directory search: keywords and filters, a page at a time. A search that finds nothing is run again with misspelt words put right; `searched_for` then shows the spelling used.

Auth: none.
MCP tool: `search_suppliers`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `q` | query | string | no | Words to search for. |
| `site` | query | "science" \| "industrial" | no | Defaults to the site this address serves. |
| `category` | query | string | no | A category slug of that site. |
| `region` | query | string | no | A state or province code as listings give it, e.g. CA or OH. |
| `cert` | query | string | no | Only suppliers whose listing names this standard, e.g. ISO 9001, AS9100 or ITAR, as `certifications` gives it. ITAR also matches a listing that states it is registered for ITAR (`itar_registered`). |
| `po` | query | "1" | no | Only suppliers that take purchase orders. |
| `page` | query | integer 1 to 1000 | no | Default 1. |
| `per_page` | query | integer 1 to 100 | no | Default 50. |

Example:

```bash
curl "https://midgardscience.aramous.com/api/v1/suppliers?category=assays&per_page=5"
```

Response 200:

```json
{
  "object": "list",
  "total": 1,
  "page": 1,
  "per_page": 5,
  "data": [
    {
      "slug": "example-lab",
      "name": "Example Lab",
      "website": "https://lab.example.com",
      "description": "Contract lab for in vitro assays.",
      "location": {
        "city": "Boston",
        "region": "MA",
        "country": "US"
      },
      "sites": [
        "science"
      ],
      "categories": [
        "assays"
      ],
      "capabilities": [],
      "certifications": [
        "ISO 17025"
      ],
      "itar_registered": null,
      "logo_url": null,
      "claimed": false,
      "verified": false,
      "badges": [],
      "services": [
        {
          "category": "assays",
          "name": "Assays & in vitro testing",
          "price_from": null,
          "price_to": null,
          "currency": "USD",
          "price_unit": null,
          "turnaround_days": [
            null,
            null
          ],
          "accepts_po": null
        }
      ]
    }
  ]
}
```

`verified`: signed Midgard's supplier agreement; paid through Midgard. Each of `badges` names a mark and, in `meaning`, what it means. `itar_registered` is true when the listing states it is registered with the US State Department (DDTC) for ITAR work, null when it does not say.

Errors:

- 400 `invalid_request`: page or per_page out of range; unknown site; a category of another site.

### GET /api/v1/suppliers/{slug}

One supplier. A listing in full: profile, services and listed prices, standards, public records (GLP, ownership, FDA FEI, CLIA where known), shared contact mailboxes with the page each is on, and `ways` to continue. A person's own address is never given.

Auth: none.
MCP tool: `get_supplier`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `slug` | path | string | yes | From a search. |

Example:

```bash
curl https://midgardscience.aramous.com/api/v1/suppliers/example-lab
```

Response 200:

```json
{
  "object": "supplier",
  "slug": "example-lab",
  "name": "Example Lab",
  "website": "https://lab.example.com",
  "description": "Contract lab for in vitro assays.",
  "location": {
    "city": "Boston",
    "region": "MA",
    "country": "US",
    "address": null
  },
  "sites": [
    "science"
  ],
  "categories": [
    "assays"
  ],
  "capabilities": [],
  "certifications": [
    "ISO 17025"
  ],
  "itar_registered": null,
  "logo_url": null,
  "claimed": false,
  "verified": false,
  "badges": [],
  "services": [
    {
      "category": "assays",
      "name": "Assays & in vitro testing",
      "price_from": null,
      "price_to": null,
      "currency": "USD",
      "price_unit": null,
      "turnaround_days": [
        null,
        null
      ],
      "accepts_po": null
    }
  ],
  "url": "https://midgardscience.aramous.com/s/example-lab",
  "company_type": null,
  "founded": null,
  "team": null,
  "partner": false,
  "standards": [
    "ISO 17025"
  ],
  "offers": [
    {
      "name": "Assays & in vitro testing",
      "description": null
    }
  ],
  "scope": {},
  "ordering": {},
  "quality": [],
  "sites_listed": [],
  "regions_served": [],
  "order_route": null,
  "contacts": [
    {
      "email": "info@example.com",
      "source_url": "https://lab.example.com/contact"
    }
  ],
  "ways": [
    {
      "way": "midgard",
      "title": "Through Midgard",
      "label": "Request a quote through Midgard",
      "note": "Midgard sends your request to the lab and keeps the order's messages, papers and payments in one place. Free to ask. 1% platform fee if you keep the order on Midgard.",
      "request": {
        "method": "POST",
        "path": "/api/v1/requests",
        "body": {
          "suppliers": [
            "example-lab"
          ]
        }
      }
    }
  ],
  "records": {
    "glp": null,
    "ownership": null,
    "fda_fei": null,
    "clia": null
  }
}
```

A listing with its own form, email or ordering service also has an `own` or `provider` way, listed first.

Errors:

- 404 `not_found`: No listed supplier with that slug on this site.

### GET /api/v1/categories

Sites, categories and request fields. Each site, its categories and the spec fields a request in each takes. `required`: a value is needed to create the request. `needed`: a value, or the key in `spec_unknown`, before it goes to suppliers (`confirm_labs`). `recommended`: worth giving, never blocks. `when`: the field applies only when another field has one of these values. `checklist`: the value goes on the list the order is accepted against. Read it before creating a request.

Auth: none.
MCP tool: `list_categories`.

Example:

```bash
curl https://midgardscience.aramous.com/api/v1/categories
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "site": "science",
      "name": "Midgard Science",
      "categories": [
        {
          "slug": "assays",
          "name": "Assays & in vitro testing",
          "unit": "samples",
          "spec": [
            {
              "key": "assay",
              "label": "Assay or readout",
              "type": "text",
              "required": true,
              "needed": false,
              "recommended": false,
              "when": null,
              "checklist": false
            },
            {
              "key": "sample_type",
              "label": "Sample type",
              "type": "text",
              "required": false,
              "needed": true,
              "recommended": false,
              "when": null,
              "checklist": false
            },
            {
              "key": "samples",
              "label": "Samples",
              "type": "select",
              "options": [
                "We ship samples to the lab",
                "Lab sources the material",
                "Not sure"
              ],
              "required": false,
              "needed": false,
              "recommended": false,
              "when": null,
              "checklist": false
            },
            {
              "key": "files",
              "label": "Protocol or sample sheet",
              "type": "file",
              "required": false,
              "needed": false,
              "recommended": false,
              "when": null,
              "checklist": false
            }
          ]
        }
      ]
    }
  ]
}
```

Shortened to one category and a few of its fields. A `select` field takes one of its `options`, exactly as written. A `file` field takes the `url` POST /api/v1/uploads returns.

### POST /api/v1/auth/code

Email a sign-in code. Mails a six-digit code to trade for a key. The answer is the same whether or not the address has been seen before. The code works once, for 10 minutes, with 5 tries; the two newest codes work.

Auth: none.
MCP tool: `sign_in`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `email` | body | string | yes | The address the key will act for. |

Example:

```bash
curl -X POST https://midgardscience.aramous.com/api/v1/auth/code \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'
```

Response 200:

```json
{
  "sent": true,
  "email": "you@company.com",
  "expires_in": 600,
  "message": "Check you@company.com for a six-digit code."
}
```

Errors:

- 400 `invalid_request`: Not an email address.
- 429 `rate_limited`: Too many codes from this network, or for this address. The answer carries `Retry-After`, the seconds to wait.

Limits: 10 codes an hour per network address, with lower limits per email address.

### POST /api/v1/auth/token

Trade the code for a key. Returns an API key (mg_...) for the email. It is shown once; only its hash is kept. Anyone with it can order as that email.

Auth: none.
MCP tool: `verify_code`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `email` | body | string | yes | The same address. |
| `code` | body | string | yes | The six digits from the email. |
| `label` | body | string, up to 80 characters | no | A name for the key, e.g. the tool that uses it. |

Example:

```bash
curl -X POST https://midgardscience.aramous.com/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com", "code": "123456", "label": "ERP"}'
```

Response 201:

```json
{
  "object": "api_key",
  "key": "mg_…",
  "key_id": "key_Pc5uF3nJ8hV2",
  "prefix": "mg_ab12cd",
  "email": "you@company.com"
}
```

Errors:

- 400 `invalid_request`: No email or no code.
- 400 `invalid_code`: The code is wrong.
- 400 `code_expired`: The code has expired or was used; ask for a new one.
- 429 `too_many_tries`: Too many wrong codes for this address; try again tomorrow.
- 429 `rate_limited`: More than 30 tries an hour from this network. The answer carries `Retry-After`, the seconds to wait.

Limits: 30 tries an hour per network address.

### GET /api/v1/me

Who the key acts for. The email, the key in use and its webhook address.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `whoami`.

Example:

```bash
curl https://midgardscience.aramous.com/api/v1/me -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "object": "me",
  "email": "you@company.com",
  "key": {
    "id": "key_Pc5uF3nJ8hV2",
    "prefix": "mg_ab12cd",
    "label": "ERP",
    "created_at": "2026-11-17T09:00:00.000Z",
    "last_used_at": "2026-11-17T09:00:00.000Z"
  },
  "webhook_url": null
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### GET /api/v1/keys

List keys. The working keys for this email, newest first, by prefix and label. `current` marks the key in use.

Auth: `Authorization: Bearer mg_...`.

Example:

```bash
curl https://midgardscience.aramous.com/api/v1/keys -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "object": "api_key",
      "id": "key_Pc5uF3nJ8hV2",
      "prefix": "mg_ab12cd",
      "label": "ERP",
      "created_at": "2026-11-17T09:00:00.000Z",
      "last_used_at": "2026-11-17T09:00:00.000Z",
      "current": true
    }
  ]
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### DELETE /api/v1/keys/{id}

Revoke a key. Revokes one of this email's keys, the one in use included.

Auth: `Authorization: Bearer mg_...`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `id` | path | string | yes | A key id from GET /api/v1/keys. |

Example:

```bash
curl -X DELETE https://midgardscience.aramous.com/api/v1/keys/key_Pc5uF3nJ8hV2 -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "object": "api_key",
  "id": "key_Pc5uF3nJ8hV2",
  "revoked": true
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 404 `not_found`: No key with that id for this email.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### POST /api/v1/uploads

Upload a file. A drawing, CAD file, sequence file, sample sheet or protocol. Put the returned `url` in the request's spec field of `type: "file"` (GET /api/v1/categories names it for each category), in POST /api/v1/requests or with the `set_spec` action. The file joins the first request that names it and is then listed in its `files`; for another request, upload it again. Over MCP, the `upload_file` tool does the same from base64 text or an https address.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `upload_file`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `file` | form | file, up to 50 MB | yes | multipart/form-data field `file`. |

Example:

```bash
curl -X POST https://midgardscience.aramous.com/api/v1/uploads -H "Authorization: Bearer $KEY" \
  -F "file=@drawing.pdf"
```

Response 201:

```json
{
  "object": "upload",
  "id": "upl_Lm2nB7vC4xZ9",
  "filename": "drawing.pdf",
  "size": 182044,
  "url": "https://midgardscience.aramous.com/f/…",
  "expires_at": "2026-12-17T09:00:00.000Z"
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 400 `invalid_request`: No `file` field.
- 400 `invalid_file`: Empty, larger than 50 MB, or a type that is not accepted.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### POST /api/v1/requests

Create a request. A request for quotes, placed for the key's email. It starts as `new`; GET /api/v1/requests/{id} lists its `suggestions`, each with the `supplier_id` for `confirm_labs`. Nothing goes to any supplier until you confirm them with the `confirm_labs` action. A retry with the same `Idempotency-Key` returns the request already created, with status 200 and an `Idempotent-Replayed: true` header. `missing` lists needed fields still open: `confirm_labs` is refused until each has a value (`set_spec`) or is in `spec_unknown`. Slugs named in `suppliers` are pre-selected (listed first) but are not asked until `confirm_labs`; a slug this site does not list is refused with a 400. `status_url` is a page a person can open. Spec values must be real: placeholders such as `...` or `TBD` are refused.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `create_request`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `site` | body | "science" \| "industrial" | yes | The site. |
| `category` | body | string | yes | A category slug of that site. |
| `title` | body | string, up to 160 characters | yes | A short title for the work. |
| `spec` | body | object | no | The category's spec fields, key to value. See GET /api/v1/categories. |
| `spec_unknown` | body | array of spec keys | no | Needed fields the person does not know. The suppliers are asked to say what they would use. |
| `quantity` | body | integer | no | Counted in the category's unit (samples for Assays & in vitro testing). |
| `details` | body | string | no | Anything else suppliers should know. |
| `needed_by` | body | string | no | A date, e.g. 2027-01-15. |
| `supplier` | body | string | no | One preferred supplier slug. |
| `suppliers` | body | array of up to 20 slugs | no | Pre-select these suppliers. They are asked only when you run `confirm_labs`. An unknown slug is refused. |
| `budget` | body | string, up to 60 characters | no | Shown to the suppliers asked. |
| `organization, country, contact_name` | body | string | no | Optional details for suppliers. |
| `Idempotency-Key` | header | string, up to 200 characters | no | A value unique to each new request, e.g. a UUID. A retry with the same value and the same body returns the request already created; the same value with any change to the body is refused with 409. |

Example:

```bash
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"}'
```

Response 201:

```json
{
  "id": "req_Xq3v9KpL2aB7",
  "object": "request",
  "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"
  },
  "spec_unknown": [],
  "missing": [],
  "quantity": 40,
  "details": null,
  "needed_by": "2027-01-15",
  "reply_by": null,
  "outcome_reason": null,
  "status": "new",
  "created_at": "2026-11-17T09:00:00.000Z",
  "updated_at": "2026-11-17T09:00:00.000Z",
  "quotes": [],
  "status_url": "https://midgardscience.aramous.com/r/req_Xq3v9KpL2aB7?t=…"
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 400 `invalid_json`: The body is not a JSON object.
- 400 `invalid_request`: An unknown site or category, a missing required field, a `select` value that is not one of its options, a placeholder value, or an `email` other than the key's. The message names the field and, for a select, its options.
- 409 `idempotency_conflict`: The Idempotency-Key was already used with a different body. Send a new key for a new request; a retry sends the same body.
- 500 `server_error`: The request could not be created; retry with the same Idempotency-Key.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### GET /api/v1/requests

List your requests. Requests placed with this key's email, newest first, including those placed on the website. Each has `late`: true when a step of the order is past its date and not marked done. Page with `starting_after`: while `has_more` is true, pass `next_starting_after` from the answer.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `list_requests`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `status` | query | string | no | One status or several, comma-separated: new, sourcing, quoted, accepted, paid, in_progress, delivered, closed, cancelled, introduced. |
| `site` | query | string | no | Only this site's requests. |
| `limit` | query | integer 1 to 100 | no | Default 100. |
| `starting_after` | query | string | no | The last id of the previous page. |

Example:

```bash
curl "https://midgardscience.aramous.com/api/v1/requests?status=quoted,delivered&limit=20" -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "id": "req_Xq3v9KpL2aB7",
      "object": "request",
      "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"
      },
      "spec_unknown": [],
      "missing": [],
      "quantity": 40,
      "details": null,
      "needed_by": "2027-01-15",
      "reply_by": "2026-11-24",
      "outcome_reason": null,
      "status": "quoted",
      "created_at": "2026-11-17T09:00:00.000Z",
      "updated_at": "2026-11-17T09:00:00.000Z",
      "quotes": [],
      "late": false
    }
  ],
  "has_more": false,
  "next_starting_after": null
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 400 `invalid_request`: An unknown status or site, limit out of range, or a starting_after id that is not yours.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### GET /api/v1/requests/{id}

One request. Status, suggested suppliers (`supplier_id` for confirm_labs), the suppliers asked (`labs`, each with its `reply_by` and, when it declined, `decline_reason`), quotes with the `ways` you can continue with each, milestones, change orders, payments, shipments, files and the timeline. After a supplier declines or misses its reply-by date, `next_suppliers` lists the next best matches to ask with `invite_more`. Each milestone has `planned_at` (the date first agreed), `expected_at`, `state` (`done`, `late`, `delayed`, `on_track` or `open`), `waiting_on` (`supplier`, `buyer` or null), `delay_reason` and `checked_in_at`; a step `waiting_on: "buyer"` can be moved with `set_milestone_date`. A file the supplier delivered has `from: "supplier"`.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `get_request`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `id` | path | string | yes | req_... |

Example:

```bash
curl https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7 -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "id": "req_Xq3v9KpL2aB7",
  "object": "request",
  "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"
  },
  "spec_unknown": [],
  "missing": [],
  "quantity": 40,
  "details": null,
  "needed_by": "2027-01-15",
  "reply_by": "2026-11-24",
  "outcome_reason": null,
  "status": "quoted",
  "created_at": "2026-11-17T09:00:00.000Z",
  "updated_at": "2026-11-17T09:00:00.000Z",
  "quotes": [
    {
      "id": "qt_Hn4sD8wQ1zR6",
      "object": "quote",
      "price": 4800,
      "currency": "USD",
      "turnaround_days": 15,
      "valid_until": "2026-12-17T00:00:00.000Z",
      "terms": null,
      "status": "sent",
      "payment_url": null,
      "paid": false,
      "lab": {
        "slug": "example-lab",
        "name": "Example Lab"
      },
      "lab_price": 4800,
      "fee": null,
      "shipping": null,
      "schedule": null,
      "ways": [
        {
          "way": "own",
          "accept": {
            "method": "POST",
            "path": "/api/v1/quotes/qt_Hn4sD8wQ1zR6/accept",
            "body": {
              "continue": "own"
            }
          }
        }
      ]
    }
  ],
  "late": false,
  "mode": null,
  "scope_of_work": [],
  "suggestions": [
    {
      "supplier_id": "sup_Tb6yE2mC9kW1",
      "slug": "example-lab",
      "name": "Example Lab",
      "reasons": [
        "Its profile lists this service."
      ],
      "picked": true
    }
  ],
  "labs": [
    {
      "rfq_id": "rfq_Gd8kM1sP5tY3",
      "slug": "example-lab",
      "name": "Example Lab",
      "status": "quoted",
      "state": "quoted",
      "sent_at": "2026-11-17T09:00:00.000Z",
      "reply_by": "2026-11-24T23:59:59.000Z",
      "decline_reason": null
    }
  ],
  "milestones": [
    {
      "stage": "kickoff",
      "planned_at": "2026-11-20T00:00:00.000Z",
      "expected_at": "2026-11-24T00:00:00.000Z",
      "done_at": null,
      "state": "delayed",
      "waiting_on": "supplier",
      "delay_reason": "Waiting on a reagent lot",
      "checked_in_at": "2026-11-17T09:00:00.000Z",
      "note": null
    }
  ],
  "change_orders": [],
  "payments": [],
  "shipments": [],
  "files": [],
  "events": [
    {
      "type": "status",
      "status": "quoted",
      "message": "Quoted",
      "created_at": "2026-11-17T09:00:00.000Z"
    }
  ]
}
```

Shortened: each way also has a title, label and note. `milestones` is filled once an order kept here is accepted.

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 404 `not_found`: No request with that id for this key's email.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### GET /api/v1/requests/{id}/events

The timeline. The request's public timeline, oldest first. Poll with `since` to get only what is new.

Auth: `Authorization: Bearer mg_...`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `id` | path | string | yes | req_... |
| `since` | query | date-time | no | Only events after this time. |

Example:

```bash
curl "https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7/events?since=2026-11-01T00:00:00Z" -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "object": "list",
  "request_status": "quoted",
  "data": [
    {
      "id": "evt_Rw7cN2hK6pQ4",
      "type": "status",
      "status": "quoted",
      "message": "Quoted",
      "created_at": "2026-11-17T09:00:00.000Z"
    }
  ]
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 404 `not_found`: No request with that id for this key's email.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### GET /api/v1/requests/{id}/messages

Read the messages. The thread, oldest first: what you sent and the record of what you did on the order (`from: "you"`) and the updates and supplier questions passed on to you (`from: "midgard"`).

Auth: `Authorization: Bearer mg_...`.
MCP tool: `get_messages`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `id` | path | string | yes | req_... |

Example:

```bash
curl https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7/messages -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "object": "list",
  "request_id": "req_Xq3v9KpL2aB7",
  "data": [
    {
      "id": "evt_Ys1fV8bT3mD5",
      "object": "message",
      "from": "you",
      "message": "Samples ship on Monday.",
      "created_at": "2026-11-17T09:00:00.000Z"
    }
  ]
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 404 `not_found`: No request with that id for this key's email.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### POST /api/v1/requests/{id}/messages

Send a message. An answer to a supplier's question, or more detail. It is passed on.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `send_message`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `id` | path | string | yes | req_... |
| `message` | body | string, up to 4000 characters | yes | The text. |

Example:

```bash
curl -X POST https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7/messages -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Samples ship on Monday."}'
```

Response 201:

```json
{
  "object": "message",
  "request_id": "req_Xq3v9KpL2aB7",
  "message": "Samples ship on Monday."
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 404 `not_found`: No request with that id for this key's email.
- 400 `invalid_request`: No message.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### POST /api/v1/requests/{id}/actions

Act on a request. Everything the order page does, one body per `action`: `confirm_labs` (status `new`: send the request to `supplierIds` from `suggestions`, or `slugs`; optional `replyBy`, YYYY-MM-DD, 2 to 30 days out, default 5 business days; refused while `missing` lists needed fields), `set_spec` (status `new`: `spec` values and `specUnknown` keys), `invite_more` (status `sourcing` or `quoted`: 1 to 3 `supplierIds` from `next_suppliers`; up to 12 suppliers per request), `set_milestone_date` (`stage`, `date`: a step that waits on you), `set_acceptance`, `answer_question` (`rfqId`, `answer`), `choose_managed` and `choose_direct` (the same as accepting a quote, with an optional `outcomeReason`), `add_shipment`, `pay` (`paymentId`: returns a card payment link), `decide_change` (`changeId`, `approve`), `accept_results` and `request_rerun` (`reason`) once delivered, `request_release` (storage). The OpenAPI description has the schema of each body.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `request_action`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `id` | path | string | yes | req_... |
| `action` | body | string | yes | One of the actions above; the other fields depend on it. |

Example:

```bash
curl -X POST https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7/actions -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"action":"confirm_labs","supplierIds":["sup_Tb6yE2mC9kW1"]}'
```

Response 200:

```json
{
  "ok": true,
  "contacted": 1,
  "chosen": 1,
  "reachable": 1,
  "not_reachable": []
}
```

`confirm_labs` returns `chosen`, `reachable` (the chosen suppliers with an email or a quote form) and `not_reachable` (names); `contacted` equals `reachable`; `invite_more` returns `invited`; `choose_managed` and `pay` return `paymentUrl` (null when invoiced); `choose_direct` returns `introducedTo`.

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 404 `not_found`: No request with that id for this key's email.
- 400 `invalid_request`: An unknown action, the action does not fit the request's status, a field is missing, or `set_spec` names a key the category does not have or a select value that is not one of its options. The message says which.
- 409 `conflict`: The request is cancelled: nothing more can be done on it.
- 500 `server_error`: The action failed; check the request before retrying.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### POST /api/v1/quotes/{id}/accept

Accept a quote. `continue: "midgard"` keeps the order on the site under the order terms (/terms): `terms_name` is the name of the person accepting them. The answer carries `payment_url` for the first card payment, or with `po` each payment is invoiced. `continue: "own"` takes the quote to the supplier directly, with no platform fee: your contact details go to the supplier and theirs appear on the timeline.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `accept_quote`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `id` | path | string | yes | qt_..., from GET /api/v1/requests/{id}. |
| `continue` | body | "midgard" \| "own" | yes | How the person continues. |
| `terms_name` | body | string | no | Required with "midgard": the name of the person accepting the order terms. |
| `po` | body | string | no | A purchase order number; payments are then invoiced. |
| `billing_email` | body | string | no | Where invoices go, if not the key's email. |
| `revision` | body | string | no | Parts: the file revision the order is built to, e.g. Rev C. |
| `outcome_reason` | body | "price" \| "lead_time" \| "capability" \| "other" | no | Optional. The main reason the other suppliers were not chosen; they are told it, never who was chosen or at what price. |

Example:

```bash
curl -X POST https://midgardscience.aramous.com/api/v1/quotes/qt_Hn4sD8wQ1zR6/accept -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"continue": "own"}'
```

Response 200:

```json
{
  "id": "qt_Hn4sD8wQ1zR6",
  "object": "quote",
  "price": 4800,
  "currency": "USD",
  "turnaround_days": 15,
  "valid_until": "2026-12-17T00:00:00.000Z",
  "terms": null,
  "status": "sent",
  "payment_url": null,
  "paid": false,
  "continue": "own",
  "supplier": "Example Lab"
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 404 `not_found`: No quote with that id on this email's requests.
- 400 `invalid_request`: No `continue`, no `terms_name` for "midgard", an unknown `outcome_reason`, or the quote can no longer be accepted.
- 500 `server_error`: The quote could not be accepted; check the request before retrying.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### POST /api/v1/requests/{id}/cancel

Cancel a request. Cancels a request that is not yet paid or under way; open quotes are withdrawn and the suppliers asked are told the request is closed. Cancelling a cancelled request returns the same answer.

Auth: `Authorization: Bearer mg_...`.
MCP tool: `cancel_request`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `id` | path | string | yes | req_... |
| `reason` | body | string | no | Optional. Internal; never sent to suppliers. |
| `outcome_reason` | body | "price" \| "lead_time" \| "capability" \| "other" | no | Optional. The main reason, told to the suppliers asked. |

Example:

```bash
curl -X POST https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7/cancel -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Ordered elsewhere", "outcome_reason": "lead_time"}'
```

Response 200:

```json
{
  "object": "request",
  "id": "req_Xq3v9KpL2aB7",
  "status": "cancelled"
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 404 `not_found`: No request with that id for this key's email.
- 400 `invalid_request`: An unknown `outcome_reason`.
- 409 `not_cancellable`: Already paid or under way.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### GET /api/v1/webhook

Read the webhook address. The callback address set for this key.

Auth: `Authorization: Bearer mg_...`.

Example:

```bash
curl https://midgardscience.aramous.com/api/v1/webhook -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "object": "webhook",
  "url": null
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### PUT /api/v1/webhook

Set the webhook address. Callbacks for requests placed with this key: `request.quoted`, `request.status_changed`, `request.message`. Each is a JSON POST `{id, type, created_at, data: {request_id, ...}}` with a `Webhook-Signature: t=<seconds>,v1=<hex>` header, where v1 is HMAC-SHA256 of `<t>.<raw body>` keyed with the secret. The secret is returned once; setting the address again makes a new one. `{"url": null}` stops callbacks.

Auth: `Authorization: Bearer mg_...`.

| Parameter | In | Type | Required | About |
|---|---|---|---|---|
| `url` | body | string \| null | yes | An https address on a public host. |

Example:

```bash
curl -X PUT https://midgardscience.aramous.com/api/v1/webhook -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/hooks/orders"}'
```

Response 200:

```json
{
  "object": "webhook",
  "url": "https://example.com/hooks/orders",
  "secret": "whsec_…"
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.
- 400 `invalid_request`: Not an https address on a public host.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### DELETE /api/v1/webhook

Stop callbacks. Removes the address and its secret.

Auth: `Authorization: Bearer mg_...`.

Example:

```bash
curl -X DELETE https://midgardscience.aramous.com/api/v1/webhook -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "object": "webhook",
  "url": null
}
```

Errors:

- 401 `unauthorized`: No key, or a key that is wrong or revoked.
- 429 `rate_limited`: More than 120 calls a minute with this key. The answer carries `Retry-After`, the seconds to wait.

Limits: 120 calls a minute per key, shared by every keyed endpoint.

### GET /api/v1/openapi.json

OpenAPI description. OpenAPI 3.1 for every endpoint here, with a schema for each body. Also listed at /.well-known/api-catalog.

Auth: none.

Example:

```bash
curl https://midgardscience.aramous.com/api/v1/openapi.json
```

Response 200:

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Ordering API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://midgardscience.aramous.com"
    }
  ],
  "paths": {}
}
```

Shortened.

## MCP tools

### list_categories

List categories. Lists each site ("science", "industrial"), its service categories and the spec fields a request in each category takes. Each field says whether it is required (a value to place the request), needed (a value or spec_unknown before confirm_labs), recommended, when it applies, and whether it goes on the acceptance checklist. Call it before create_request to get a valid site, category and spec keys. No sign-in needed.

Sign-in: not needed. Hints: Read-only (readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false).

Example arguments:

```json
{}
```

Returns the same object as `GET /api/v1/categories`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 500 `server_error`: Something failed on the server; try again.

### search_suppliers

Search the directory. Keyword search of the public supplier directory, the same search as the website. Returns a page of listings with location, categories, certificates and services as each listing states them. Use it to browse or to apply exact filters: category, state or province, certificate, purchase orders. For work described in plain language and ranked by fit, use find_suppliers. No sign-in needed.

Sign-in: not needed. Hints: Read-only (readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false).

| Argument | Type | Required | About |
|---|---|---|---|
| `q` | string | no | Words to search for. |
| `site` | string | no | The site: "science" or "industrial". Defaults to the site this address serves. |
| `category` | string | no | A category slug from list_categories. |
| `region` | string | no | A state or province code as listings give it, e.g. CA or OH. |
| `cert` | string | no | Only listings that name this certificate or standard, as the tags in `certifications` give it, e.g. ISO 9001, AS9100 or ITAR. ITAR also matches a listing that states it is registered with the US State Department (`itar_registered`). |
| `accepts_po` | boolean | no | Only suppliers that take purchase orders. |
| `page` | integer | no | The page to return, from 1. Default 1. The answer's `total` counts every match. |
| `per_page` | integer | no | Listings per page, 1 to 100. Default 50. |

Example arguments:

```json
{
  "category": "assays",
  "q": "kinase",
  "per_page": 5
}
```

Returns the same object as `GET /api/v1/suppliers`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 400 `invalid_request`: Unknown site, or a category of another site.
- 500 `server_error`: Something failed on the server; try again.

### find_suppliers

Find suppliers for a request. The first call for "find a lab, CRO, shop or supplier for this work". Describe the work in plain language; returns up to 10 suppliers ranked by fit (`fit`: "strong" when the listing states the work and every standard and place the query requires; "possible" when it states part of it, or when the search fell back to keywords), each with the reasons taken from its profile, and a request_draft to pass to create_request once the person has checked it. `missing` lists details still needed: ask the person about each. One with not_known_allowed true may go in spec_unknown when they don't know it. Takes up to a minute. No sign-in needed: 10 searches an hour per network address, 100 an hour when signed in.

Sign-in: not needed. Hints: Read-only (readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false).

| Argument | Type | Required | About |
|---|---|---|---|
| `query` | string | yes | The work, in the person's words: what, how many, any standards and deadlines. |
| `site` | string | no | The site: "science" or "industrial". Defaults to the site this address serves. |
| `category` | string | no | A category slug from list_categories. |
| `region` | "any" \| "na" \| "us" \| "eu" \| "india" \| "asia" | no | Region key: any, na, us, eu, india, asia. "eu" includes the UK. For a US state or a city, name it in the query, or use search_suppliers with region set to the state code. |
| `standard` | string | no | Only suppliers whose listing names this standard, e.g. GLP or ISO 13485. |
| `limit` | integer | no | How many suppliers, 1 to 10. Default 8. |

Example arguments:

```json
{
  "query": "Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis",
  "limit": 3
}
```

Returns the same object as `POST /api/v1/search`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 400 `invalid_request`: Unknown site, category or region.
- 429 `rate_limited`: Over the hourly search limit. The message says when to try again.
- 500 `server_error`: Something failed on the server; try again.

### get_supplier

Get a supplier. One listing by slug (from find_suppliers or search_suppliers): profile, services and listed prices, standards as the listing names them (the supplier confirms them in its quote), public records, shared contact mailboxes, and `ways` to continue: contact the supplier directly, or ask for a quote through a request. No sign-in needed.

Sign-in: not needed. Hints: Read-only (readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false).

| Argument | Type | Required | About |
|---|---|---|---|
| `slug` | string | yes | The supplier's slug, from a search. |

Example arguments:

```json
{
  "slug": "example-lab"
}
```

Returns the same object as `GET /api/v1/suppliers/{slug}`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 404 `not_found`: No listed supplier with that slug.
- 500 `server_error`: Something failed on the server; try again.

### sign_in

Sign in: send a code. Step 1 of signing in, needed only to order or read orders. Emails a six-digit code to the person's own address: ask them for it and never guess it. Then ask them for the code and call verify_code. Orders are placed for, and visible to, this address. Each call sends another email; the two newest codes work. Not needed when the connection sends an API key.

Sign-in: not needed. Hints: Adds, does not overwrite, Not safe to repeat, Reaches outside the server (readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true).

| Argument | Type | Required | About |
|---|---|---|---|
| `email` | string | yes | The person's email address. |

Example arguments:

```json
{
  "email": "you@company.com"
}
```

Returns the same object as `POST /api/v1/auth/code`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 400 `no_session`: The client keeps no Mcp-Session-Id, so it cannot hold a sign-in; connect with an API key instead.
- 400 `invalid_request`: Not an email address.
- 429 `rate_limited`: Too many codes from this network, or for this address.
- 500 `server_error`: Something failed on the server; try again.

### verify_code

Sign in: check the code. Step 2 of signing in: checks the six-digit code the person read from the email sent by sign_in, and signs this connection in as that email. The code works once, for 10 minutes, with 5 tries.

Sign-in: not needed. Hints: Adds, does not overwrite, Not safe to repeat, Stays on the server (readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint false).

| Argument | Type | Required | About |
|---|---|---|---|
| `email` | string | yes | The same email as in sign_in. |
| `code` | string or integer | yes | The six-digit code the person read from the email. |

Example arguments:

```json
{
  "email": "you@company.com",
  "code": "123456"
}
```

Returns `{"signed_in": true, "email", "message"}` as JSON text; the session is signed in and no key is returned.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 400 `no_session`: The client keeps no Mcp-Session-Id.
- 400 `invalid_code`: The code is wrong.
- 400 `code_expired`: Expired or used; call sign_in again.
- 429 `too_many_tries`: Too many wrong codes for this address.
- 500 `server_error`: Something failed on the server; try again.

### whoami

Who is signed in. The email this connection acts for, and the key in use. Use it to check the sign-in before ordering.

Sign-in: required. Hints: Read-only (readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false).

Example arguments:

```json
{}
```

Returns the same object as `GET /api/v1/me`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 500 `server_error`: Something failed on the server; try again.

### upload_file

Upload a file. Stores a drawing, CAD file, sequence file, sample sheet or protocol for a request, the same as POST /api/v1/uploads. Send the file as content_base64 with its filename, or as url, an https address the server can download it from without signing in. Up to 50 MB; content_base64 suits files up to 3 MB, larger files go by url. The filename's extension decides whether the type is accepted. Returns the file's url: put it in the category's spec field of type file (list_categories), in create_request or with request_action set_spec. The file joins the first request that names it; for another request, upload it again. Downloads by url: 30 an hour.

Sign-in: required. Hints: Adds, does not overwrite, Not safe to repeat, Reaches outside the server (readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true).

| Argument | Type | Required | About |
|---|---|---|---|
| `filename` | string | no | The file's name with its extension, e.g. bracket.step or plasmid.gb. Needed with content_base64; with url, the name the address or its download gives is used when this is left out. |
| `content_base64` | string | no | The file's bytes, base64-encoded (a data: URL works too), for files up to 3 MB. Send this or url, not both. |
| `url` | string | no | An https address the file downloads from without signing in, up to 50 MB. Send this or content_base64, not both. |

Example arguments:

```json
{
  "url": "https://files.example.com/drawing-rev-c.pdf"
}
```

Returns the same object as `POST /api/v1/uploads`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 400 `invalid_request`: Neither or both of content_base64 and url, no filename with content_base64, base64 that does not decode, or a url that is not https on a public host.
- 400 `invalid_file`: Empty, larger than 50 MB, or a type that is not accepted.
- 400 `fetch_failed`: The url did not answer with the file within 30 seconds.
- 429 `rate_limited`: More than 30 downloads by url this hour.
- 500 `server_error`: Something failed on the server; try again.

### create_request

Create a request. Places a request for quotes as the signed-in email, on a site and category from list_categories. A request_draft from find_suppliers is a good start; check the details with the person first. The request starts as `new` with suggested suppliers, and nothing goes to any supplier until request_action confirm_labs. `suppliers` only pre-selects slugs (an unknown slug is refused); they are asked when you run confirm_labs. Returns the request and a status_url the person can open. Send idempotency_key, a value unique to this request, so a retry with the same arguments returns the same request; reusing it with any other arguments is refused. To attach a drawing or other file, store it with upload_file and put the returned url in the category's field of type file (list_categories). The response's missing lists needed fields still open; confirm_labs refuses until each has a value or is in spec_unknown.

Sign-in: required. Hints: Adds, does not overwrite, Not safe to repeat, Reaches outside the server (readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true).

| Argument | Type | Required | About |
|---|---|---|---|
| `site` | string | yes | The site: "science" or "industrial". |
| `category` | string | yes | A category slug from list_categories. |
| `title` | string | yes | A short title for the work. |
| `spec` | object | no | The category's spec fields, key to value (see list_categories). A select field takes one of its options; a file field takes a url from upload_file. |
| `spec_unknown` | array of string | no | Spec keys the person does not know. Needed fields must have a value or be listed here before confirm_labs. |
| `quantity` | integer | no | How many, as a whole number counted in the category's unit (list_categories gives `unit`: samples, parts, ...). |
| `details` | string | no | Anything else the suppliers should know. |
| `needed_by` | string | no | A date (2027-01-15) or the buyer's words (mid January). |
| `budget` | string | no | Shown to the suppliers asked. |
| `supplier` | string | no | One preferred supplier slug. |
| `suppliers` | array of string | no | Supplier slugs to pre-select. Nobody is asked until confirm_labs. |
| `contact_name` | string | no | The person's name, shown to the suppliers asked. |
| `organization` | string | no | The person's company or institution, shown to the suppliers asked. |
| `country` | string | no | The country the work is for or ships to. |
| `idempotency_key` | string | no | A value unique to this request, e.g. a UUID. Send the same value with the same arguments on a retry to get the request already created instead of a second one; the same value with any argument changed is refused with idempotency_conflict. |

Example arguments:

```json
{
  "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",
  "idempotency_key": "3f6c2a1e-8d4b-4e57-9a0c-5b7e2d1f9c84"
}
```

Returns the same object as `POST /api/v1/requests`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 400 `invalid_request`: Unknown site or category, a missing required field, a select value that is not one of its options, or a placeholder value. The message names the field.
- 409 `idempotency_conflict`: The idempotency_key was already used with different arguments; send a new one.
- 500 `server_error`: Something failed on the server; try again.

### list_requests

List requests. The signed-in email's requests, newest first, including orders placed on the website. Filter by status to find the ones waiting on the person (quoted, delivered). `late` is true when a step is past its date.

Sign-in: required. Hints: Read-only (readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false).

| Argument | Type | Required | About |
|---|---|---|---|
| `status` | string | no | One status or several, comma-separated: new, sourcing, quoted, accepted, paid, in_progress, delivered, closed, cancelled, introduced. |
| `site` | string | no | Only this site's requests: "science" or "industrial". Left out, every site's. |
| `limit` | integer | no | Default 20. |
| `starting_after` | string | no | To page: the last id of the previous page. |

Example arguments:

```json
{
  "status": "quoted,delivered",
  "limit": 20
}
```

Returns the same object as `GET /api/v1/requests`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 400 `invalid_request`: Unknown status or site, or a starting_after id that is not yours.
- 500 `server_error`: Something failed on the server; try again.

### get_request

Get a request. One request: status, suggested suppliers (supplier_id for confirm_labs), the date suppliers are asked to reply by (reply_by), each asked supplier's status, quotes (each with its id for accept_quote and its `ways` to continue), milestones (each with its state and who it waits on), payments, shipments, files and the public timeline. After a supplier declines or misses reply_by, next_suppliers lists who to invite with invite_more. `missing` lists needed fields still open. Check it again later to see when status becomes `quoted`.

Sign-in: required. Hints: Read-only (readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false).

| Argument | Type | Required | About |
|---|---|---|---|
| `request_id` | string | yes | The request id (req_...). |

Example arguments:

```json
{
  "request_id": "req_Xq3v9KpL2aB7"
}
```

Returns the same object as `GET /api/v1/requests/{id}`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 404 `not_found`: No request with that id for this account.
- 500 `server_error`: Something failed on the server; try again.

### get_messages

Read messages. The message thread on a request, oldest first: what the person sent ("you") and the updates and supplier questions passed on to them ("midgard").

Sign-in: required. Hints: Read-only (readOnlyHint true, destructiveHint false, idempotentHint true, openWorldHint false).

| Argument | Type | Required | About |
|---|---|---|---|
| `request_id` | string | yes | The request id (req_...). |

Example arguments:

```json
{
  "request_id": "req_Xq3v9KpL2aB7"
}
```

Returns the same object as `GET /api/v1/requests/{id}/messages`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 404 `not_found`: No request with that id for this account.
- 500 `server_error`: Something failed on the server; try again.

### send_message

Send a message. Adds a message to a request's thread: an answer to a supplier's question, or more detail. It is passed on. Each call adds another message.

Sign-in: required. Hints: Adds, does not overwrite, Not safe to repeat, Reaches outside the server (readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true).

| Argument | Type | Required | About |
|---|---|---|---|
| `request_id` | string | yes | The request id (req_...). |
| `message` | string | yes | The text to pass on, up to 4000 characters. |

Example arguments:

```json
{
  "request_id": "req_Xq3v9KpL2aB7",
  "message": "Samples ship on Monday."
}
```

Returns the same object as `POST /api/v1/requests/{id}/messages`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 404 `not_found`: No request with that id for this account.
- 500 `server_error`: Something failed on the server; try again.

### accept_quote

Accept a quote. Accepts a quote the way the person chose; it cannot be undone, so confirm with them first. continue "midgard" keeps the order on the site under the order terms: terms_name must be the full name the person typed to accept the terms; ask them for it and never fill it in yourself. The answer may carry payment_url, a Stripe Checkout link for the person to open and pay; you cannot pay. continue "own" takes the quote to the supplier directly; the supplier's contact details then appear on the timeline.

Sign-in: required. Hints: Cannot be undone, Not safe to repeat, Reaches outside the server (readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true).

| Argument | Type | Required | About |
|---|---|---|---|
| `quote_id` | string | yes | The quote id (qt_...), from get_request. |
| `continue` | "midgard" \| "own" | yes | How the person continues. |
| `terms_name` | string | no | For "midgard": the name the person typed to accept the order terms. |
| `po` | string | no | A purchase order number. With one, payments are invoiced. |
| `billing_email` | string | no | Where invoices go, if not the signed-in email. |
| `revision` | string | no | Parts: the file revision the order is built to, e.g. Rev C. |
| `outcome_reason` | "price" \| "lead_time" \| "capability" \| "other" | no | Optional. The main reason, shared with the suppliers not chosen: price, lead_time, capability or other. Ask the person; never choose it yourself. |

Example arguments:

```json
{
  "quote_id": "qt_Hn4sD8wQ1zR6",
  "continue": "midgard",
  "terms_name": "<the name the person typed>"
}
```

Returns the same object as `POST /api/v1/quotes/{id}/accept`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 404 `not_found`: No quote with that id.
- 400 `invalid_request`: No terms_name for "midgard", an unknown outcome_reason, or the quote can no longer be accepted.
- 500 `server_error`: Something failed on the server; try again.

### request_action

Act on a request. The order page's other actions; confirm each with the person first. confirm_labs (status new): send the request to suppliers by supplier_ids (from suggestions) or slugs, with an optional reply_by date. invite_more (status sourcing or quoted): send to more suppliers by supplier_ids from next_suppliers. set_spec (status new): fill spec fields or mark them spec_unknown. set_milestone_date: move the date of a step that waits on the person (stage, date). set_acceptance (status new): what the order must meet; fixed once the requests have gone out. answer_question: answer a supplier's question (rfq_id, answer). add_shipment: record what is being sent (material, samples). pay: returns payment_url, a Stripe Checkout link for the person to open; you cannot pay. decide_change: approve or decline a change (change_id, approve). accept_results or request_rerun (reason) once delivered. request_release: storage, give notice to leave. To accept a quote use accept_quote.

Sign-in: required. Hints: Cannot be undone, Not safe to repeat, Reaches outside the server (readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true).

| Argument | Type | Required | About |
|---|---|---|---|
| `request_id` | string | yes | The request id (req_...). |
| `action` | "confirm_labs" \| "invite_more" \| "set_spec" \| "set_milestone_date" \| "set_acceptance" \| "answer_question" \| "add_shipment" \| "pay" \| "decide_change" \| "accept_results" \| "request_rerun" \| "request_release" | yes | Which action. The other arguments it reads are named after it in each argument's description. |
| `supplier_ids` | array of string | no | confirm_labs: ids from the request's suggestions. invite_more: 1 to 3 ids from next_suppliers. |
| `reply_by` | string | no | confirm_labs: YYYY-MM-DD, 2 to 30 days from today, the date suppliers are asked to reply by. Default 5 business days. |
| `spec` | object | no | set_spec: spec fields to fill, key to value. |
| `spec_unknown` | array of string | no | set_spec: spec keys the person does not know. |
| `stage` | string | no | set_milestone_date: the step (stage from get_request milestones) whose waiting_on is buyer. |
| `date` | string | no | set_milestone_date: the new date, YYYY-MM-DD. |
| `slugs` | array of string | no | confirm_labs: supplier slugs. |
| `acceptance` | object | no | set_acceptance: term to value. |
| `rfq_id` | string | no | answer_question: the question's rfq id. |
| `answer` | string | no | answer_question: the answer. |
| `material` | object | no | add_shipment: what is being sent. |
| `samples` | array of object | no | add_shipment: the samples in the shipment, each with your id for it, a description and an optional amount. |
| `booked_by` | "client" \| "lab" | no | add_shipment: who books the courier. |
| `payment_id` | string | no | pay: the payment id (pay_...) from get_request. |
| `change_id` | string | no | decide_change: the change id (co_...). |
| `approve` | boolean | no | decide_change: true to approve. |
| `reason` | string | no | request_rerun: what is wrong. |
| `kind` | string | no | request_rerun: the kind of problem. |
| `quantity` | string | no | request_rerun: how much is affected. |
| `photos` | array of string | no | request_rerun: links to files uploaded to this order. |

Example arguments:

```json
{
  "request_id": "req_Xq3v9KpL2aB7",
  "action": "confirm_labs",
  "supplier_ids": [
    "sup_Tb6yE2mC9kW1"
  ]
}
```

Returns the same object as `POST /api/v1/requests/{id}/actions`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 404 `not_found`: No request with that id for this account.
- 400 `invalid_request`: The action does not fit the request's status, a field is missing, confirm_labs while needed fields are open, or set_spec with a key the category does not have or a select value that is not one of its options.
- 500 `server_error`: Something failed on the server; try again.

### cancel_request

Cancel a request. Cancels a request before it is paid; open quotes are withdrawn and the suppliers asked are told it is closed. It cannot be undone, so confirm with the person first. `reason` stays internal; outcome_reason is what the suppliers are told.

Sign-in: required. Hints: Cannot be undone, Safe to repeat, Reaches outside the server (readOnlyHint false, destructiveHint true, idempotentHint true, openWorldHint true).

| Argument | Type | Required | About |
|---|---|---|---|
| `request_id` | string | yes | The request id (req_...). |
| `reason` | string | no | Internal; never sent to suppliers. |
| `outcome_reason` | "price" \| "lead_time" \| "capability" \| "other" | no | Optional. The main reason, told to the suppliers asked: price, lead_time, capability or other. Ask the person; never choose it yourself. |

Example arguments:

```json
{
  "request_id": "req_Xq3v9KpL2aB7",
  "reason": "Ordered elsewhere",
  "outcome_reason": "lead_time"
}
```

Returns the same object as `POST /api/v1/requests/{id}/cancel`, as JSON text.

Errors (an `isError` result with `{"error": {"code", "message"}}`):

- 401 `sign_in_required`: Not signed in: call sign_in and verify_code, or connect with an API key.
- 404 `not_found`: No request with that id for this account.
- 400 `invalid_request`: An unknown outcome_reason.
- 409 `not_cancellable`: Already paid or under way.
- 500 `server_error`: Something failed on the server; try again.
