# Midgard Industrial API

> Midgard Industrial passes requests for quotes to independent suppliers and relays their quotes, for custom parts (CNC machining, Sheet metal & laser cutting, 3D printing, PCBs & assembly, Finishing & assembly, Testing & inspection); materials (Metals, Plastics & resins, Chemicals & coatings, Packaging, Electronic & MRO components). Search the directory, send a request, receive quotes, accept one and follow the order, over JSON or MCP.

Base URL: https://midgardindustrial.aramous.com. OpenAPI: https://midgardindustrial.aramous.com/api/v1/openapi.json. MCP: https://midgardindustrial.aramous.com/api/mcp. HTML version: https://midgardindustrial.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`, with `suggestions`), 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).

## Quick start: curl

```bash
# 1. Search: no key needed
curl -X POST https://midgardindustrial.aramous.com/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"50 anodized 6061 aluminum brackets, CNC machined from a STEP file, +/-0.05 mm","limit":3}'

# 2. Get a key: a code by email, then trade it
curl -X POST https://midgardindustrial.aramous.com/api/v1/auth/code \
  -H "Content-Type: application/json" \
  -d '{"email": "you@company.com"}'
curl -X POST https://midgardindustrial.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://midgardindustrial.aramous.com/api/v1/requests \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: my-order-123" \
  -H "Content-Type: application/json" \
  -d '{"site":"industrial","category":"cnc-machining","title":"50 anodized 6061 aluminum brackets","spec":{"material":"6061-T6 aluminum","finish":"anodized black","export_control":"No controlled data"},"quantity":50,"needed_by":"2027-01-15"}'

# 4. See its suggestions, then ask the suppliers you pick
curl https://midgardindustrial.aramous.com/api/v1/requests/req_... -H "Authorization: Bearer $KEY"
curl -X POST https://midgardindustrial.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://midgardindustrial.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):
        return self.call("POST", f"/api/v1/requests/{request_id}/cancel", {"reason": reason} if reason else {})


if __name__ == "__main__":
    query = " ".join(sys.argv[1:]) or "50 anodized 6061 aluminum brackets, CNC machined from a STEP file, +/-0.05 mm"
    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
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("50 anodized 6061 aluminum brackets, CNC machined from a STEP file, +/-0.05 mm")
draft = found["request_draft"]
# Check the draft with the person and fill in what found["missing"] lists.
# 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")
req = m.create_request(draft, idempotency_key="my-order-123")
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://midgardindustrial.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>;

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 }) {
    return this.call("POST", `/api/v1/quotes/${quoteId}/accept`, choice);
  }
  cancel(id: string, reason?: string) {
    return this.call("POST", `/api/v1/requests/${id}/cancel`, reason ? { reason } : {});
  }
}

// Run directly: search and print the suppliers that fit.
if (process.argv[1]?.endsWith("midgard.ts")) {
  const query = process.argv.slice(2).join(" ") || "50 anodized 6061 aluminum brackets, CNC machined from a STEP file, +/-0.05 mm";
  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 Industrial: https://midgardindustrial.aramous.com/api/mcp
- Midgard Science: https://midgardscience.aramous.com/api/mcp

Claude Code:

```bash
claude mcp add --transport http midgard-industrial https://midgardindustrial.aramous.com/api/mcp
claude mcp add --transport http midgard-science https://midgardscience.aramous.com/api/mcp

# With a key, so there is nothing to sign in to
claude mcp add --transport http midgard-industrial https://midgardindustrial.aramous.com/api/mcp \
  --header "Authorization: Bearer mg_..."
```

Cursor (`~/.cursor/mcp.json` or `.cursor/mcp.json` in a project):

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

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

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

Any client that speaks Streamable HTTP:

```json
{
  "mcpServers": {
    "midgard-industrial": {
      "type": "http",
      "url": "https://midgardindustrial.aramous.com/api/mcp"
    }
  }
}
```

A client that only runs local (stdio) servers, through the mcp-remote bridge:

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

Check the connection and list the tools:

```bash
npx @modelcontextprotocol/inspector --cli https://midgardindustrial.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 still needed before ordering. 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. |
| `standard` | body | string | no | A standard the supplier must hold, e.g. GLP or ISO 13485. |
| `limit` | body | integer 1 to 10 | no | Default 8. |

Example:

```bash
curl -X POST https://midgardindustrial.aramous.com/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query":"50 anodized 6061 aluminum brackets, CNC machined from a STEP file, +/-0.05 mm","limit":3}'
```

Response 200:

```json
{
  "object": "search_result",
  "query": "50 anodized 6061 aluminum brackets, CNC machined from a STEP file, +/-0.05 mm",
  "site": "industrial",
  "category": "cnc-machining",
  "summary": null,
  "ranked_by": "model",
  "scoped_by": "model",
  "suppliers": [
    {
      "slug": "example-machine-works",
      "name": "Example Machine Works",
      "location": {
        "city": "Dayton",
        "region": "OH",
        "country": "US"
      },
      "website": "https://shop.example.com",
      "logo_url": null,
      "url": "https://midgardindustrial.aramous.com/s/example-machine-works",
      "fit": "strong",
      "reasons": [
        "Its profile lists this service."
      ],
      "standards": [
        "ISO 9001"
      ],
      "direct": {
        "kind": "form",
        "href": "https://shop.example.com/quote",
        "opens": "form"
      },
      "provider": null
    }
  ],
  "request_draft": {
    "site": "industrial",
    "category": "cnc-machining",
    "title": "50 anodized 6061 aluminum brackets",
    "spec": {
      "material": "6061-T6 aluminum",
      "finish": "anodized black",
      "export_control": "No controlled data"
    },
    "quantity": 50,
    "needed_by": "2027-01-15",
    "details": "50 anodized 6061 aluminum brackets, CNC machined from a STEP file, +/-0.05 mm",
    "suppliers": [
      "example-machine-works"
    ]
  },
  "missing": [
    {
      "question": "How many?",
      "options": []
    }
  ],
  "questions": []
}
```

`ranked_by` is `keywords` and `scoped_by` is `rules` when the model was not used.

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.
- 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 | A certificate or standard, e.g. ISO 9001. |
| `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://midgardindustrial.aramous.com/api/v1/suppliers?category=cnc-machining&per_page=5"
```

Response 200:

```json
{
  "object": "list",
  "total": 1,
  "page": 1,
  "per_page": 5,
  "data": [
    {
      "slug": "example-machine-works",
      "name": "Example Machine Works",
      "website": "https://shop.example.com",
      "description": "CNC machining and finishing shop.",
      "location": {
        "city": "Dayton",
        "region": "OH",
        "country": "US"
      },
      "sites": [
        "industrial"
      ],
      "categories": [
        "cnc-machining"
      ],
      "capabilities": [],
      "certifications": [
        "ISO 9001"
      ],
      "logo_url": null,
      "claimed": false,
      "verified": false,
      "badges": [],
      "services": [
        {
          "category": "cnc-machining",
          "name": "CNC machining",
          "price_from": null,
          "price_to": null,
          "currency": "USD",
          "price_unit": null,
          "turnaround_days": [
            null,
            null
          ],
          "accepts_po": null
        }
      ]
    }
  ]
}
```

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://midgardindustrial.aramous.com/api/v1/suppliers/example-machine-works
```

Response 200:

```json
{
  "object": "supplier",
  "slug": "example-machine-works",
  "name": "Example Machine Works",
  "website": "https://shop.example.com",
  "description": "CNC machining and finishing shop.",
  "location": {
    "city": "Dayton",
    "region": "OH",
    "country": "US",
    "address": null
  },
  "sites": [
    "industrial"
  ],
  "categories": [
    "cnc-machining"
  ],
  "capabilities": [],
  "certifications": [
    "ISO 9001"
  ],
  "logo_url": null,
  "claimed": false,
  "verified": false,
  "badges": [],
  "services": [
    {
      "category": "cnc-machining",
      "name": "CNC machining",
      "price_from": null,
      "price_to": null,
      "currency": "USD",
      "price_unit": null,
      "turnaround_days": [
        null,
        null
      ],
      "accepts_po": null
    }
  ],
  "url": "https://midgardindustrial.aramous.com/s/example-machine-works",
  "company_type": null,
  "founded": null,
  "team": null,
  "partner": false,
  "standards": [
    "ISO 9001"
  ],
  "offers": [
    {
      "name": "CNC machining",
      "description": null
    }
  ],
  "scope": {},
  "ordering": {},
  "quality": [],
  "sites_listed": [],
  "regions_served": [],
  "order_route": null,
  "contacts": [
    {
      "email": "info@example.com",
      "source_url": "https://shop.example.com/contact"
    }
  ],
  "ways": [
    {
      "way": "midgard",
      "title": "Through Midgard",
      "label": "Request a quote through Midgard",
      "note": "Midgard sends your request to the shop 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-machine-works"
          ]
        }
      }
    }
  ],
  "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, with `required` marked. Read it before creating a request.

Auth: none.
MCP tool: `list_categories`.

Example:

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

Response 200:

```json
{
  "object": "list",
  "data": [
    {
      "site": "industrial",
      "name": "Midgard Industrial",
      "categories": [
        {
          "slug": "cnc-machining",
          "name": "CNC machining",
          "unit": "parts",
          "spec": [
            {
              "key": "material",
              "label": "Material",
              "type": "text",
              "required": true
            },
            {
              "key": "finish",
              "label": "Finish",
              "type": "text",
              "required": false
            }
          ]
        }
      ]
    }
  ]
}
```

Shortened to one category and two fields.

### 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://midgardindustrial.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.

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://midgardindustrial.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.

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://midgardindustrial.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.

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://midgardindustrial.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.

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://midgardindustrial.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.
- 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 a request's spec field.

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

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

Example:

```bash
curl -X POST https://midgardindustrial.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://midgardindustrial.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.
- 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` with `suggestions`; nothing goes to any supplier until you confirm them with the `confirm_labs` action. 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. |
| `quantity` | body | integer | no | Counted in the category's unit (parts for CNC machining). |
| `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. |
| `organization, country, budget, contact_name` | body | string | no | Optional details for suppliers. |
| `Idempotency-Key` | header | string | no | A retry with the same value returns the request already created. |

Example:

```bash
curl -X POST https://midgardindustrial.aramous.com/api/v1/requests -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: my-order-123" \
  -H "Content-Type: application/json" \
  -d '{"site":"industrial","category":"cnc-machining","title":"50 anodized 6061 aluminum brackets","spec":{"material":"6061-T6 aluminum","finish":"anodized black","export_control":"No controlled data"},"quantity":50,"needed_by":"2027-01-15"}'
```

Response 201:

```json
{
  "id": "req_Xq3v9KpL2aB7",
  "object": "request",
  "site": "industrial",
  "category": "cnc-machining",
  "title": "50 anodized 6061 aluminum brackets",
  "spec": {
    "material": "6061-T6 aluminum",
    "finish": "anodized black",
    "export_control": "No controlled data"
  },
  "quantity": 50,
  "details": null,
  "needed_by": "2027-01-15",
  "status": "new",
  "created_at": "2026-11-17T09:00:00.000Z",
  "updated_at": "2026-11-17T09:00:00.000Z",
  "quotes": [],
  "status_url": "https://midgardindustrial.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.
- 400 `invalid_json`: The body is not a JSON object.
- 400 `invalid_request`: An unknown site or category, a missing required field, a placeholder value, or an `email` other than the key's. The message names the field.
- 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. Page with `starting_after`.

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://midgardindustrial.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": "industrial",
      "category": "cnc-machining",
      "title": "50 anodized 6061 aluminum brackets",
      "spec": {
        "material": "6061-T6 aluminum",
        "finish": "anodized black",
        "export_control": "No controlled data"
      },
      "quantity": 50,
      "details": null,
      "needed_by": "2027-01-15",
      "status": "quoted",
      "created_at": "2026-11-17T09:00:00.000Z",
      "updated_at": "2026-11-17T09:00:00.000Z",
      "quotes": []
    }
  ],
  "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.
- 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, quotes with the `ways` you can continue with each, milestones, change orders, payments, shipments, files and the timeline. 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://midgardindustrial.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7 -H "Authorization: Bearer $KEY"
```

Response 200:

```json
{
  "id": "req_Xq3v9KpL2aB7",
  "object": "request",
  "site": "industrial",
  "category": "cnc-machining",
  "title": "50 anodized 6061 aluminum brackets",
  "spec": {
    "material": "6061-T6 aluminum",
    "finish": "anodized black",
    "export_control": "No controlled data"
  },
  "quantity": 50,
  "details": null,
  "needed_by": "2027-01-15",
  "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-machine-works",
        "name": "Example Machine Works"
      },
      "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"
            }
          }
        }
      ]
    }
  ],
  "mode": null,
  "scope_of_work": [],
  "suggestions": [
    {
      "supplier_id": "sup_Tb6yE2mC9kW1",
      "slug": "example-machine-works",
      "name": "Example Machine Works",
      "reasons": [
        "Its profile lists this service."
      ],
      "picked": true
    }
  ],
  "labs": [
    {
      "rfq_id": "rfq_Gd8kM1sP5tY3",
      "slug": "example-machine-works",
      "name": "Example Machine Works",
      "status": "quoted",
      "state": "quoted",
      "sent_at": "2026-11-17T09:00:00.000Z"
    }
  ],
  "milestones": [],
  "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.

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.
- 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://midgardindustrial.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.
- 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 (`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://midgardindustrial.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.
- 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://midgardindustrial.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.
- 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`), `set_acceptance`, `answer_question` (`rfqId`, `answer`), `choose_managed` and `choose_direct` (the same as accepting a quote), `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://midgardindustrial.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
}
```

`confirm_labs` returns `contacted`; `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.
- 404 `not_found`: No request with that id for this key's email.
- 400 `invalid_request`: The action does not fit the request's status, or a field is missing. The message says which.
- 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. |

Example:

```bash
curl -X POST https://midgardindustrial.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 Machine Works"
}
```

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.
- 404 `not_found`: No quote with that id on this email's requests.
- 400 `invalid_request`: No `continue`, no `terms_name` for "midgard", 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. 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. |

Example:

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

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.
- 404 `not_found`: No request with that id for this key's email.
- 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://midgardindustrial.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.

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://midgardindustrial.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.
- 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://midgardindustrial.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.

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://midgardindustrial.aramous.com/api/v1/openapi.json
```

Response 200:

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Ordering API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "https://midgardindustrial.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, marking the required ones. 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. 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 | A certificate or standard, e.g. ISO 9001. |
| `accepts_po` | boolean | no | Only suppliers that take purchase orders. |
| `page` | integer | no |  |
| `per_page` | integer | no |  |

Example arguments:

```json
{
  "category": "cnc-machining",
  "q": "aluminum",
  "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, 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 before ordering. 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. |
| `standard` | string | no | A quality standard the supplier must hold, e.g. GLP or ISO 13485. |
| `limit` | integer | no | How many suppliers, 1 to 10. Default 8. |

Example arguments:

```json
{
  "query": "50 anodized 6061 aluminum brackets, CNC machined from a STEP file, +/-0.05 mm",
  "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.
- 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, 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-machine-works"
}
```

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 email or suppliers (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.

### 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 so a retry returns the same request.

Sign-in: required. Hints: Adds, does not overwrite, Not safe to repeat, Reaches email or suppliers (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). |
| `quantity` | integer | no |  |
| `details` | string | no | Anything else the suppliers should know. |
| `needed_by` | string | no | A date, e.g. 2027-01-15. |
| `budget` | string | no |  |
| `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 |  |
| `organization` | string | no |  |
| `country` | string | no |  |
| `idempotency_key` | string | no | Send the same value on a retry to get the request already created instead of a second one. |

Example arguments:

```json
{
  "site": "industrial",
  "category": "cnc-machining",
  "title": "50 anodized 6061 aluminum brackets",
  "spec": {
    "material": "6061-T6 aluminum",
    "finish": "anodized black",
    "export_control": "No controlled data"
  },
  "quantity": 50,
  "needed_by": "2027-01-15",
  "idempotency_key": "my-order-123"
}
```

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 or a placeholder value.
- 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).

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 | The site: "science" or "industrial". Defaults to the site this address serves. |
| `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), quotes (each with its id for accept_quote and its `ways` to continue), milestones, payments, shipments, files and the public timeline. 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 email or suppliers (readOnlyHint false, destructiveHint false, idempotentHint false, openWorldHint true).

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

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 email or suppliers (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. |

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", 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. set_acceptance: what the order must meet. 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 email or suppliers (readOnlyHint false, destructiveHint true, idempotentHint false, openWorldHint true).

| Argument | Type | Required | About |
|---|---|---|---|
| `request_id` | string | yes | The request id (req_...). |
| `action` | "confirm_labs" \| "set_acceptance" \| "answer_question" \| "add_shipment" \| "pay" \| "decide_change" \| "accept_results" \| "request_rerun" \| "request_release" | yes |  |
| `supplier_ids` | array of string | no | confirm_labs: ids from the request's suggestions. |
| `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 |  |
| `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, or a field is missing.
- 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. It cannot be undone, so confirm with the person first.

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

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

Example arguments:

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

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.
- 409 `not_cancellable`: Already paid or under way.
- 500 `server_error`: Something failed on the server; try again.
