API reference
Endpoints
Base URL https://midgardscience.aramous.com. JSON in and out. Errors are {"error": {"code", "message"}} with an HTTP status. The same calls as OpenAPI 3.1.
- 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 thekeyasAuthorization: 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) andRateLimit-Policy(e.g.120;w=60). A 429 addsRetry-After, the seconds to wait. - Paging
- GET /api/v1/suppliers takes
pageandper_pageand answers withtotal. GET /api/v1/requests takeslimitandstarting_afterand answers withhas_moreandnext_starting_after. - Retries
- POST /api/v1/requests takes an
Idempotency-Keyheader: a new value for each request, the same value to retry it. A retry with the same body answers 200 withIdempotent-Replayed: true; the same value with any change to the body answers 409idempotency_conflict. Cancelling twice answers the same. - Files
- Upload with POST /api/v1/uploads (multipart field
file), or over MCP with theupload_filetool (base64 or an https address), then put theurlin the category's spec field oftype: "file".
Find suppliers for work described in plain words
POST /api/v1/search
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.
No key needed; a key raises the limit. MCP tool: find_suppliers.
Parameters
- query body, string, 6 to 3000 characters, requiredThe work: what, how many, standards, deadlines.
- site body, "science" | "industrial"Defaults to the site this address serves.
- category body, stringA category slug from GET /api/v1/categories. Leave it out to let the search choose.
- region body, "any" | "na" | "us" | "eu" | "india" | "asia""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 byregion. - standard body, stringOnly suppliers whose listing names this standard, e.g. GLP or ISO 13485.
- limit body, integer 1 to 10Default 8.
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}'{
"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
- 400invalid_jsonThe body is not a JSON object.
- 400invalid_requestquery too short or too long; unknown site, category or region; limit out of range. The message names the field.
- 401unauthorizedA key was sent and is not valid.
- 429rate_limitedOver the hourly limit. The answer carries
Retry-After, the seconds to wait. - 500server_errorThe 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.
Search and page through the directory
GET /api/v1/suppliers
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.
No key needed. MCP tool: search_suppliers.
Parameters
- q query, stringWords to search for.
- site query, "science" | "industrial"Defaults to the site this address serves.
- category query, stringA category slug of that site.
- region query, stringA state or province code as listings give it, e.g. CA or OH.
- cert query, stringOnly suppliers whose listing names this standard, e.g. ISO 9001, AS9100 or ITAR, as
certificationsgives it. ITAR also matches a listing that states it is registered for ITAR (itar_registered). - po query, "1"Only suppliers that take purchase orders.
- page query, integer 1 to 1000Default 1.
- per_page query, integer 1 to 100Default 50.
curl "https://midgardscience.aramous.com/api/v1/suppliers?category=assays&per_page=5"
{
"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
- 400invalid_requestpage or per_page out of range; unknown site; a category of another site.
One supplier
GET /api/v1/suppliers/{slug}
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.
No key needed. MCP tool: get_supplier.
Parameters
- slug path, string, requiredFrom a search.
curl https://midgardscience.aramous.com/api/v1/suppliers/example-lab
{
"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
- 404not_foundNo listed supplier with that slug on this site.
Sites, categories and request fields
GET /api/v1/categories
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.
No key needed. MCP tool: list_categories.
curl https://midgardscience.aramous.com/api/v1/categories
{
"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.
Email a sign-in code
POST /api/v1/auth/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.
No key needed. MCP tool: sign_in.
Parameters
- email body, string, requiredThe address the key will act for.
curl -X POST https://midgardscience.aramous.com/api/v1/auth/code \
-H "Content-Type: application/json" \
-d '{"email": "you@company.com"}'{
"sent": true,
"email": "you@company.com",
"expires_in": 600,
"message": "Check you@company.com for a six-digit code."
}Errors
- 400invalid_requestNot an email address.
- 429rate_limitedToo 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.
Trade the code for a key
POST /api/v1/auth/token
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.
No key needed. MCP tool: verify_code.
Parameters
- email body, string, requiredThe same address.
- code body, string, requiredThe six digits from the email.
- label body, string, up to 80 charactersA name for the key, e.g. the tool that uses it.
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"}'{
"object": "api_key",
"key": "mg_…",
"key_id": "key_Pc5uF3nJ8hV2",
"prefix": "mg_ab12cd",
"email": "you@company.com"
}Errors
- 400invalid_requestNo email or no code.
- 400invalid_codeThe code is wrong.
- 400code_expiredThe code has expired or was used; ask for a new one.
- 429too_many_triesToo many wrong codes for this address; try again tomorrow.
- 429rate_limitedMore 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.
Who the key acts for
GET /api/v1/me
The email, the key in use and its webhook address.
Needs a key: Authorization: Bearer mg_... MCP tool: whoami.
curl https://midgardscience.aramous.com/api/v1/me -H "Authorization: Bearer $KEY"
{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore 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.
List keys
GET /api/v1/keys
The working keys for this email, newest first, by prefix and label. current marks the key in use.
Needs a key: Authorization: Bearer mg_...
curl https://midgardscience.aramous.com/api/v1/keys -H "Authorization: Bearer $KEY"
{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore 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.
Revoke a key
DELETE /api/v1/keys/{id}
Revokes one of this email's keys, the one in use included.
Needs a key: Authorization: Bearer mg_...
Parameters
- id path, string, requiredA key id from GET /api/v1/keys.
curl -X DELETE https://midgardscience.aramous.com/api/v1/keys/key_Pc5uF3nJ8hV2 -H "Authorization: Bearer $KEY"
{
"object": "api_key",
"id": "key_Pc5uF3nJ8hV2",
"revoked": true
}Errors
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 404not_foundNo key with that id for this email.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Upload a file
POST /api/v1/uploads
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.
Needs a key: Authorization: Bearer mg_... MCP tool: upload_file.
Parameters
- file form, file, up to 50 MB, requiredmultipart/form-data field
file.
curl -X POST https://midgardscience.aramous.com/api/v1/uploads -H "Authorization: Bearer $KEY" \ -F "file=@drawing.pdf"
{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 400invalid_requestNo
filefield. - 400invalid_fileEmpty, larger than 50 MB, or a type that is not accepted.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Create a request
POST /api/v1/requests
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.
Needs a key: Authorization: Bearer mg_... MCP tool: create_request.
Parameters
- site body, "science" | "industrial", requiredThe site.
- category body, string, requiredA category slug of that site.
- title body, string, up to 160 characters, requiredA short title for the work.
- spec body, objectThe category's spec fields, key to value. See GET /api/v1/categories.
- spec_unknown body, array of spec keysNeeded fields the person does not know. The suppliers are asked to say what they would use.
- quantity body, integerCounted in the category's unit (samples for Assays & in vitro testing).
- details body, stringAnything else suppliers should know.
- needed_by body, stringA date, e.g. 2027-01-15.
- supplier body, stringOne preferred supplier slug.
- suppliers body, array of up to 20 slugsPre-select these suppliers. They are asked only when you run
confirm_labs. An unknown slug is refused. - budget body, string, up to 60 charactersShown to the suppliers asked.
- organization, country, contact_name body, stringOptional details for suppliers.
- Idempotency-Key header, string, up to 200 charactersA 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.
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"}'{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 400invalid_jsonThe body is not a JSON object.
- 400invalid_requestAn unknown site or category, a missing required field, a
selectvalue that is not one of its options, a placeholder value, or anemailother than the key's. The message names the field and, for a select, its options. - 409idempotency_conflictThe Idempotency-Key was already used with a different body. Send a new key for a new request; a retry sends the same body.
- 500server_errorThe request could not be created; retry with the same Idempotency-Key.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
List your requests
GET /api/v1/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.
Needs a key: Authorization: Bearer mg_... MCP tool: list_requests.
Parameters
- status query, stringOne status or several, comma-separated: new, sourcing, quoted, accepted, paid, in_progress, delivered, closed, cancelled, introduced.
- site query, stringOnly this site's requests.
- limit query, integer 1 to 100Default 100.
- starting_after query, stringThe last id of the previous page.
curl "https://midgardscience.aramous.com/api/v1/requests?status=quoted,delivered&limit=20" -H "Authorization: Bearer $KEY"
{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 400invalid_requestAn 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.
One request
GET /api/v1/requests/{id}
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".
Needs a key: Authorization: Bearer mg_... MCP tool: get_request.
Parameters
- id path, string, requiredreq_...
curl https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7 -H "Authorization: Bearer $KEY"
{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 404not_foundNo request with that id for this key's email.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
The timeline
GET /api/v1/requests/{id}/events
The request's public timeline, oldest first. Poll with since to get only what is new.
Needs a key: Authorization: Bearer mg_...
Parameters
- id path, string, requiredreq_...
- since query, date-timeOnly events after this time.
curl "https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7/events?since=2026-11-01T00:00:00Z" -H "Authorization: Bearer $KEY"
{
"object": "list",
"request_status": "quoted",
"data": [
{
"id": "evt_Rw7cN2hK6pQ4",
"type": "status",
"status": "quoted",
"message": "Quoted",
"created_at": "2026-11-17T09:00:00.000Z"
}
]
}Errors
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 404not_foundNo request with that id for this key's email.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Read the messages
GET /api/v1/requests/{id}/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").
Needs a key: Authorization: Bearer mg_... MCP tool: get_messages.
Parameters
- id path, string, requiredreq_...
curl https://midgardscience.aramous.com/api/v1/requests/req_Xq3v9KpL2aB7/messages -H "Authorization: Bearer $KEY"
{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 404not_foundNo request with that id for this key's email.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Send a message
POST /api/v1/requests/{id}/messages
An answer to a supplier's question, or more detail. It is passed on.
Needs a key: Authorization: Bearer mg_... MCP tool: send_message.
Parameters
- id path, string, requiredreq_...
- message body, string, up to 4000 characters, requiredThe text.
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."}'{
"object": "message",
"request_id": "req_Xq3v9KpL2aB7",
"message": "Samples ship on Monday."
}Errors
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 404not_foundNo request with that id for this key's email.
- 400invalid_requestNo message.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Act on a request
POST /api/v1/requests/{id}/actions
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.
Needs a key: Authorization: Bearer mg_... MCP tool: request_action.
Parameters
- id path, string, requiredreq_...
- action body, string, requiredOne of the actions above; the other fields depend on it.
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"]}'{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 404not_foundNo request with that id for this key's email.
- 400invalid_requestAn unknown action, the action does not fit the request's status, a field is missing, or
set_specnames a key the category does not have or a select value that is not one of its options. The message says which. - 409conflictThe request is cancelled: nothing more can be done on it.
- 500server_errorThe action failed; check the request before retrying.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Accept a quote
POST /api/v1/quotes/{id}/accept
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.
Needs a key: Authorization: Bearer mg_... MCP tool: accept_quote.
Parameters
- id path, string, requiredqt_..., from GET /api/v1/requests/{id}.
- continue body, "midgard" | "own", requiredHow the person continues.
- terms_name body, stringRequired with "midgard": the name of the person accepting the order terms.
- po body, stringA purchase order number; payments are then invoiced.
- billing_email body, stringWhere invoices go, if not the key's email.
- revision body, stringParts: the file revision the order is built to, e.g. Rev C.
- outcome_reason body, "price" | "lead_time" | "capability" | "other"Optional. The main reason the other suppliers were not chosen; they are told it, never who was chosen or at what price.
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"}'{
"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
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 404not_foundNo quote with that id on this email's requests.
- 400invalid_requestNo
continue, noterms_namefor "midgard", an unknownoutcome_reason, or the quote can no longer be accepted. - 500server_errorThe quote could not be accepted; check the request before retrying.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Cancel a request
POST /api/v1/requests/{id}/cancel
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.
Needs a key: Authorization: Bearer mg_... MCP tool: cancel_request.
Parameters
- id path, string, requiredreq_...
- reason body, stringOptional. Internal; never sent to suppliers.
- outcome_reason body, "price" | "lead_time" | "capability" | "other"Optional. The main reason, told to the suppliers asked.
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"}'{
"object": "request",
"id": "req_Xq3v9KpL2aB7",
"status": "cancelled"
}Errors
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 404not_foundNo request with that id for this key's email.
- 400invalid_requestAn unknown
outcome_reason. - 409not_cancellableAlready paid or under way.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Read the webhook address
GET /api/v1/webhook
The callback address set for this key.
Needs a key: Authorization: Bearer mg_...
curl https://midgardscience.aramous.com/api/v1/webhook -H "Authorization: Bearer $KEY"
{
"object": "webhook",
"url": null
}Errors
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore 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.
Set the webhook address
PUT /api/v1/webhook
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.
Needs a key: Authorization: Bearer mg_...
Parameters
- url body, string | null, requiredAn https address on a public host.
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"}'{
"object": "webhook",
"url": "https://example.com/hooks/orders",
"secret": "whsec_…"
}Errors
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore than 120 calls a minute with this key. The answer carries
Retry-After, the seconds to wait. - 400invalid_requestNot an https address on a public host.
Limits: 120 calls a minute per key, shared by every keyed endpoint.
Stop callbacks
DELETE /api/v1/webhook
Removes the address and its secret.
Needs a key: Authorization: Bearer mg_...
curl -X DELETE https://midgardscience.aramous.com/api/v1/webhook -H "Authorization: Bearer $KEY"
{
"object": "webhook",
"url": null
}Errors
- 401unauthorizedNo key, or a key that is wrong or revoked.
- 429rate_limitedMore 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.
OpenAPI description
GET /api/v1/openapi.json
OpenAPI 3.1 for every endpoint here, with a schema for each body. Also listed at /.well-known/api-catalog.
No key needed.
curl https://midgardscience.aramous.com/api/v1/openapi.json
{
"openapi": "3.1.0",
"info": {
"title": "Ordering API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://midgardscience.aramous.com"
}
],
"paths": {}
}Shortened.