{"openapi":"3.1.0","info":{"title":"Ordering API","version":"1.0.0","description":"Search suppliers, send them a request, receive their quotes, accept one and follow the order. Docs with examples for every operation: https://midgardindustrial.aramous.com/developers/api. Searching needs no key. To order: get a key by email (POST /api/v1/auth/code with your email, then POST /api/v1/auth/token with the six-digit code from the email) and send it as `Authorization: Bearer mg_...`. A key acts for its email: it sees every request placed with that address, on the website too. The same API is an MCP server for AI agents at https://midgardindustrial.aramous.com/api/mcp. The steps: 1. search (POST /api/v1/search with the work in plain words returns ranked suppliers and a request draft) and upload any files (POST /api/v1/uploads); 2. create a request (POST /api/v1/requests): it starts with status `new` and a list of `suggestions`; 3. say which suppliers to ask (POST /api/v1/requests/{id}/actions with `confirm_labs`): the status becomes `sourcing` and quote requests go out; 4. wait for status `quoted` (poll the events or set a webhook); 5. accept a quote and say how you continue (POST /api/v1/quotes/{id}/accept with `continue`: `midgard` to keep the order here, `own` to deal with the supplier on your own; or the `choose_managed` and `choose_direct` actions). The supplier does the work and is responsible for it."},"servers":[{"url":"https://midgardindustrial.aramous.com"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"A key from POST /api/v1/auth/token or /developers (mg_...). Keys made before mg_ (sk_live_...) still work."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}}}}},"Quote":{"type":"object","properties":{"id":{"type":"string"},"price":{"type":"number"},"currency":{"type":"string"},"turnaround_days":{"type":["integer","null"]},"valid_until":{"type":["string","null"],"format":"date-time"},"terms":{"type":["string","null"]},"status":{"type":"string","enum":["sent","accepted","expired","withdrawn"]},"payment_url":{"type":["string","null"],"description":"Card checkout link once accepted"},"paid":{"type":"boolean"},"ways":{"type":"array","items":{"$ref":"#/components/schemas/QuoteWay"},"description":"GET /api/v1/requests/{id} only. How you can continue with this quote; empty unless the quote is open and the request is `quoted`."}}},"QuoteWay":{"type":"object","properties":{"way":{"type":"string","enum":["own","provider","midgard"],"description":"`own`: deal with the supplier yourself. `provider`: order through the supplier's own ordering service. `midgard`: keep the order here."},"title":{"type":"string"},"label":{"type":"string"},"note":{"type":"string"},"accept":{"type":"object","description":"`own` and `midgard`: the call that takes this way","properties":{"method":{"type":"string"},"path":{"type":"string"},"body":{"type":"object"}}},"url":{"type":"string","description":"`provider`: the page to continue on"},"terms_url":{"type":"string","description":"`midgard`: the order terms"}}},"Message":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["message"]},"from":{"type":"string","enum":["you","midgard"],"description":"`you`: sent by you. `midgard`: an update or a supplier's question passed on to you."},"message":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}},"SearchResult":{"type":"object","properties":{"object":{"type":"string","enum":["search_result"]},"query":{"type":"string"},"site":{"type":"string","enum":["science","industrial"]},"category":{"type":"string"},"summary":{"type":["string","null"]},"ranked_by":{"type":"string","enum":["model","keywords"]},"scoped_by":{"type":"string","enum":["model","rules"]},"suppliers":{"type":"array","items":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"location":{"type":"object"},"website":{"type":["string","null"]},"url":{"type":"string"},"fit":{"type":"string","enum":["strong","possible"]},"reasons":{"type":"array","items":{"type":"string"},"description":"Taken from the supplier's profile"},"standards":{"type":"array","items":{"type":"string"}},"direct":{"type":["object","null"],"description":"The supplier's own way to order or ask for a quote"},"provider":{"type":["object","null"]}}}},"request_draft":{"allOf":[{"$ref":"#/components/schemas/NewRequest"}],"description":"Check it, fill in what `missing` lists, then send it to POST /api/v1/requests"},"missing":{"type":"array","items":{"type":"object","properties":{"question":{"type":"string"},"options":{"type":"array","items":{"type":"string"}}}}},"questions":{"type":"array","items":{"type":"string"}}}},"Request":{"type":"object","properties":{"id":{"type":"string"},"site":{"type":"string","enum":["science","industrial"]},"category":{"type":"string"},"title":{"type":"string"},"spec":{"type":"object","additionalProperties":{"type":"string"}},"quantity":{"type":["integer","null"]},"status":{"type":"string","enum":["new","sourcing","quoted","accepted","paid","in_progress","delivered","closed","cancelled","introduced"],"description":"`introduced`: you continued on your own with the supplier; nothing more happens here."},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/Quote"}},"created_at":{"type":"string","format":"date-time"}}},"NewRequest":{"type":"object","required":["site","category","title"],"properties":{"site":{"type":"string","enum":["science","industrial"]},"category":{"type":"string","enum":["assays","protein-production","dmpk-tox","cell-line-development","sequencing","biologics-manufacturing","custom-peptides","compounds","cnc-machining","sheet-metal","3d-printing","pcb","finishing","testing-inspection","metals","plastics","chemicals-coatings","packaging","components"],"description":"See GET /api/v1/categories for each category's spec fields"},"title":{"type":"string","maxLength":160},"spec":{"type":"object","additionalProperties":{"type":"string"}},"quantity":{"type":"integer"},"needed_by":{"type":"string"},"details":{"type":"string"},"supplier":{"type":"string","description":"Preferred supplier slug (optional)"},"suppliers":{"type":"array","items":{"type":"string"},"maxItems":20,"description":"Supplier slugs to request quotes from (from GET /api/v1/suppliers)"},"email":{"type":"string","format":"email","description":"The key's own email. Leave it out; any other address is refused."},"organization":{"type":"string"},"country":{"type":"string"}}}}},"paths":{"/api/v1/auth/code":{"post":{"summary":"Email a six-digit sign-in code","description":"The code works once, for 10 minutes, with 5 tries. Asking again replaces the earlier code.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"}}}}}},"responses":{"200":{"description":"Sent","content":{"application/json":{"example":{"sent":true,"email":"you@company.com","expires_in":600,"message":"Check you@company.com for a six-digit code."}}}},"400":{"description":"`invalid_request`: Not an email address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Too many codes from this network, or for this address.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"authCode","tags":["Keys"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#auth-code","description":"Docs. MCP tool: sign_in"}}},"/api/v1/auth/token":{"post":{"summary":"Trade the code for an API key","description":"The key is shown once. Anyone with it can order as you, so keep it secret.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","code"],"properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","pattern":"^[0-9]{6}$"},"label":{"type":"string","maxLength":80,"description":"A name for the key, e.g. the tool that uses it"}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["api_key"]},"key":{"type":"string","description":"mg_..., shown once"},"key_id":{"type":"string"},"prefix":{"type":"string"},"email":{"type":"string"}}},"example":{"object":"api_key","key":"mg_…","key_id":"key_Pc5uF3nJ8hV2","prefix":"mg_ab12cd","email":"you@company.com"}}}},"400":{"description":"`invalid_request`: No email or no code. `invalid_code`: The code is wrong. `code_expired`: The code has expired or was used; ask for a new one.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`too_many_tries`: Too many wrong codes for this address; try again tomorrow. `rate_limited`: More than 30 tries an hour from this network.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"authToken","tags":["Keys"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#auth-token","description":"Docs. MCP tool: verify_code"}}},"/api/v1/me":{"get":{"summary":"The email this key acts for, the key and its webhook","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"me","tags":["Keys"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#me","description":"Docs. MCP tool: whoami"}}},"/api/v1/keys":{"get":{"summary":"This email's keys (prefix and label only); `current` marks the key in use","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}]}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listKeys","tags":["Keys"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#list-keys","description":"Docs"}}},"/api/v1/keys/{id}":{"delete":{"summary":"Revoke a key","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Revoked","content":{"application/json":{"example":{"object":"api_key","id":"key_Pc5uF3nJ8hV2","revoked":true}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No key with that id for this email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"revokeKey","tags":["Keys"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#revoke-key","description":"Docs"}}},"/api/v1/search":{"post":{"summary":"Find suppliers for work described in plain words","description":"Returns suppliers ranked by fit, each with the reasons from its profile, and a request draft for POST /api/v1/requests. No key needed: 10 searches an hour per address, 100 an hour with a key. Takes up to a minute.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":6,"maxLength":3000},"site":{"type":"string","enum":["science","industrial"],"description":"Defaults to the site this host serves"},"category":{"type":"string","enum":["assays","protein-production","dmpk-tox","cell-line-development","sequencing","biologics-manufacturing","custom-peptides","compounds","cnc-machining","sheet-metal","3d-printing","pcb","finishing","testing-inspection","metals","plastics","chemicals-coatings","packaging","components"],"description":"Leave it out to let the search choose"},"region":{"type":"string","enum":["any","na","us","eu","india","asia"],"description":"Region key. `eu` includes the UK."},"standard":{"type":"string","description":"A standard the supplier must hold, e.g. GLP"},"limit":{"type":"integer","minimum":1,"maximum":10,"default":8}}},"examples":{"pk":{"summary":"A PK study","value":{"query":"Mouse PK study for 3 small-molecule compounds, non-GLP, with LC-MS/MS bioanalysis","limit":5}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResult"},"example":{"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":[]}}}},"400":{"description":"`invalid_json`: The body is not a JSON object. `invalid_request`: query too short or too long; unknown site, category or region; limit out of range. The message names the field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: A key was sent and is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: Over the hourly limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`: The search failed; try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"search","tags":["Directory"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#search","description":"Docs. MCP tool: find_suppliers"},"security":[{},{"bearer":[]}]}},"/api/v1/suppliers/{slug}":{"get":{"summary":"One supplier: profile, services and prices, standards, shared contact addresses and the ways to continue","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}}}}},"404":{"description":"`not_found`: No listed supplier with that slug on this site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getSupplier","tags":["Directory"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#get-supplier","description":"Docs. MCP tool: get_supplier"}}},"/api/v1/categories":{"get":{"summary":"Sites, categories and spec fields","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}]}]}]}}}}},"operationId":"categories","tags":["Directory"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#categories","description":"Docs. MCP tool: list_categories"}}},"/api/v1/openapi.json":{"get":{"summary":"This OpenAPI description","responses":{"200":{"description":"OK","content":{"application/json":{"example":{"openapi":"3.1.0","info":{"title":"Ordering API","version":"1.0.0"},"servers":[{"url":"https://midgardindustrial.aramous.com"}],"paths":{}}}}}},"operationId":"openapi","tags":["Directory"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#openapi","description":"Docs"}}},"/api/v1/suppliers":{"get":{"summary":"Listed suppliers","parameters":[{"name":"site","in":"query","schema":{"type":"string","enum":["science","industrial"]},"description":"Defaults to the site this host serves"},{"name":"category","in":"query","schema":{"type":"string","enum":["assays","protein-production","dmpk-tox","cell-line-development","sequencing","biologics-manufacturing","custom-peptides","compounds","cnc-machining","sheet-metal","3d-printing","pcb","finishing","testing-inspection","metals","plastics","chemicals-coatings","packaging","components"]}},{"name":"q","in":"query","schema":{"type":"string","maxLength":200},"description":"Words to search for"},{"name":"region","in":"query","schema":{"type":"string"},"description":"A state or province code as listings give it, e.g. CA or OH"},{"name":"cert","in":"query","schema":{"type":"string"},"description":"A certificate or standard, e.g. ISO 9001"},{"name":"po","in":"query","schema":{"type":"string","enum":["1"]},"description":"Only suppliers that take purchase orders"},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"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}]}]}}}},"400":{"description":"`invalid_request`: page or per_page out of range; unknown site; a category of another site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listSuppliers","tags":["Directory"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#list-suppliers","description":"Docs. MCP tool: search_suppliers"}}},"/api/v1/requests":{"post":{"summary":"Create a request","security":[{"bearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","schema":{"type":"string"},"description":"Retries with the same key return the request already created"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewRequest"}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"},"example":{"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=…"}}}},"400":{"description":"`invalid_json`: The body is not a JSON object. `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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`: The request could not be created; retry with the same Idempotency-Key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createRequest","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#create-request","description":"Docs. MCP tool: create_request"}},"get":{"summary":"Your requests, newest first","description":"Requests placed with this key or by its email on the website. To page, pass `next_starting_after` as `starting_after`.","security":[{"bearer":[]}],"parameters":[{"name":"status","in":"query","schema":{"type":"string"},"description":"One status or several, comma-separated, e.g. `quoted,accepted`"},{"name":"site","in":"query","schema":{"type":"string","enum":["science","industrial"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":100}},{"name":"starting_after","in":"query","schema":{"type":"string"},"description":"The last request id of the previous page"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Request"}},"has_more":{"type":"boolean"},"next_starting_after":{"type":["string","null"]}}},"example":{"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}}}},"400":{"description":"`invalid_request`: An unknown status or site, limit out of range, or a starting_after id that is not yours.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"listRequests","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#list-requests","description":"Docs. MCP tool: list_requests"}}},"/api/v1/requests/{id}":{"get":{"summary":"Status, quotes and timeline","description":"Also returns `files`: every file on the order. Each has `from` (`supplier` or `client`) and `kind`. A file the supplier delivered has kind `lab_result` on every kind of order; one of the order's papers has kind `paper`.","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"},"example":{"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"}]}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No request with that id for this key's email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getRequest","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#get-request","description":"Docs. MCP tool: get_request"}}},"/api/v1/requests/{id}/events":{"get":{"summary":"Public timeline, oldest first","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Only events after this time"}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"object":"list","request_status":"quoted","data":[{"id":"evt_Rw7cN2hK6pQ4","type":"status","status":"quoted","message":"Quoted","created_at":"2026-11-17T09:00:00.000Z"}]}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No request with that id for this key's email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"events","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#events","description":"Docs"}}},"/api/v1/requests/{id}/messages":{"get":{"summary":"The message thread, oldest first","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"request_id":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}},"example":{"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"}]}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No request with that id for this key's email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"messages","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#messages","description":"Docs. MCP tool: get_messages"}},"post":{"summary":"Send a message on a request (answers, extra detail)","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","maxLength":4000}}}}}},"responses":{"201":{"description":"Sent","content":{"application/json":{"example":{"object":"message","request_id":"req_Xq3v9KpL2aB7","message":"Samples ship on Monday."}}}},"400":{"description":"`invalid_request`: No message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No request with that id for this key's email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"sendMessage","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#send-message","description":"Docs. MCP tool: send_message"}}},"/api/v1/requests/{id}/actions":{"post":{"summary":"Act on a request: choose suppliers, choose a quote, pay, accept the order","description":"One body per action; the schema lists each. `confirm_labs` (status `new` only) sends the request to the suppliers named by `supplierIds` (ids from the request's `suggestions`) or `slugs` (from GET /api/v1/suppliers). `set_acceptance` records what the order must meet before quotes are compared. `answer_question` answers a supplier's question. `choose_managed` accepts a quote and keeps the order here under the order terms; `choose_direct` takes the quote to the supplier on your own. `add_shipment` records what you are sending to the supplier. `pay` returns a card payment link for a payment that is due. `decide_change` approves or declines a change. `accept_results` accepts the delivered order; `request_rerun` raises an issue with it. `request_release` gives notice to leave on a storage order.","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","title":"confirm_labs","description":"Send the request to these suppliers. Status `new` only. Give `supplierIds` or `slugs`.","required":["action"],"properties":{"action":{"type":"string","enum":["confirm_labs"]},"supplierIds":{"type":"array","items":{"type":"string"},"maxItems":12,"description":"Ids from the request's `suggestions`"},"slugs":{"type":"array","items":{"type":"string"},"maxItems":12,"description":"Slugs from GET /api/v1/suppliers"}}},{"type":"object","title":"set_acceptance","description":"What the order must meet, agreed before quotes are compared.","required":["action","acceptance"],"properties":{"action":{"type":"string","enum":["set_acceptance"]},"acceptance":{"type":"object","additionalProperties":{"type":"string","maxLength":300},"description":"Term name to its value"}}},{"type":"object","title":"answer_question","description":"Answer a supplier's question.","required":["action","rfqId","answer"],"properties":{"action":{"type":"string","enum":["answer_question"]},"rfqId":{"type":"string"},"answer":{"type":"string","minLength":2,"maxLength":1500}}},{"type":"object","title":"choose_managed","description":"Accept a quote and keep the order here under the order terms. A 1% platform fee is added as its own line.","required":["action","quoteId","termsName"],"properties":{"action":{"type":"string","enum":["choose_managed"]},"quoteId":{"type":"string","description":"A quote on this request (qt_...)"},"termsName":{"type":"string","minLength":2,"maxLength":120,"description":"The name of the person accepting the order terms"},"po":{"type":"string","maxLength":80,"description":"Purchase order number. With one, payments are invoiced."},"billingEmail":{"type":"string","format":"email"},"revision":{"type":"string","maxLength":20,"description":"Parts: the file revision the order is built to, e.g. Rev C"}}},{"type":"object","title":"choose_direct","description":"Take a quote to the supplier on your own. Free. Your contact details go to the supplier; theirs appear on the timeline.","required":["action","quoteId"],"properties":{"action":{"type":"string","enum":["choose_direct"]},"quoteId":{"type":"string","description":"A quote on this request (qt_...)"}}},{"type":"object","title":"add_shipment","description":"Record what you are sending to the supplier. Only on an order kept here.","required":["action","material"],"properties":{"action":{"type":"string","enum":["add_shipment"]},"material":{"type":"object","required":["kind","description","temperature","fromCountry","toCountry"],"properties":{"kind":{"type":"string","enum":["compound","protein","plasmid","cell_line","human_sample","animal_sample","animal_derived","other"]},"description":{"type":"string","minLength":3,"maxLength":500},"amount":{"type":"string","maxLength":100},"temperature":{"type":"string","enum":["ambient","chilled","dry_ice","ln2"]},"infectious":{"type":"boolean"},"gmo":{"type":"boolean"},"thirdParty":{"type":"boolean"},"hasCoa":{"type":"boolean"},"fromCountry":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter country code"},"toCountry":{"type":"string","minLength":2,"maxLength":2,"description":"Two-letter country code"},"dryIceKg":{"type":"number","minimum":0,"maximum":200},"finishedGoods":{"type":"boolean"}}},"samples":{"type":"array","maxItems":500,"items":{"type":"object","required":["id","description"],"properties":{"id":{"type":"string"},"description":{"type":"string"},"amount":{"type":"string"}}}},"bookedBy":{"type":"string","enum":["client","lab"],"default":"client","description":"Who books the courier: you or the supplier"}}},{"type":"object","title":"pay","description":"A card payment link for a payment that is due.","required":["action","paymentId"],"properties":{"action":{"type":"string","enum":["pay"]},"paymentId":{"type":"string"}}},{"type":"object","title":"decide_change","description":"Approve or decline a change the supplier proposed.","required":["action","changeId","approve"],"properties":{"action":{"type":"string","enum":["decide_change"]},"changeId":{"type":"string"},"approve":{"type":"boolean"}}},{"type":"object","title":"accept_results","description":"Accept what was delivered. Status `delivered` only.","required":["action"],"properties":{"action":{"type":"string","enum":["accept_results"]}}},{"type":"object","title":"request_rerun","description":"Raise an issue with what was delivered. Status `delivered` only.","required":["action","reason"],"properties":{"action":{"type":"string","enum":["request_rerun"]},"reason":{"type":"string","minLength":5,"maxLength":1500},"kind":{"type":"string","description":"The kind of problem, e.g. `quality` or `damage`. Defaults to the order's general kind."},"quantity":{"type":"string","maxLength":120,"description":"How much is affected, e.g. 6 of 20 pieces"},"photos":{"type":"array","maxItems":10,"items":{"type":"string"},"description":"Links to files uploaded to this order (/f/...)"}}},{"type":"object","title":"request_release","description":"Storage orders: give notice to leave. The release period agreed on the quote starts now.","required":["action"],"properties":{"action":{"type":"string","enum":["request_release"]}}}],"discriminator":{"propertyName":"action"}},"examples":{"confirm":{"summary":"Ask two suppliers for quotes","value":{"action":"confirm_labs","slugs":["supplier-slug-one","supplier-slug-two"]}},"keep":{"summary":"Accept a quote and keep the order here","value":{"action":"choose_managed","quoteId":"qt_...","termsName":"Ada Lovelace"}},"own":{"summary":"Take a quote to the supplier on your own","value":{"action":"choose_direct","quoteId":"qt_..."}},"issue":{"summary":"Raise an issue with what was delivered","value":{"action":"request_rerun","reason":"Six of twenty pieces arrived bent.","quantity":"6 of 20 pieces"}}}}}},"responses":{"200":{"description":"Done: `{ok: true}` plus, for `confirm_labs`, `contacted` (how many suppliers); for `choose_managed` and `pay`, `paymentUrl` (null when the order is invoiced); for `choose_direct`, `introducedTo` (the supplier's name; their contact details are on the request's timeline).","content":{"application/json":{"example":{"ok":true,"contacted":1}}}},"400":{"description":"`invalid_request`: The action does not fit the request's status, or a field is missing. The message says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No request with that id for this key's email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`: The action failed; check the request before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"actions","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#actions","description":"Docs. MCP tool: request_action"}}},"/api/v1/requests/{id}/cancel":{"post":{"summary":"Cancel a request before payment","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}}}}},"responses":{"200":{"description":"Cancelled","content":{"application/json":{"example":{"object":"request","id":"req_Xq3v9KpL2aB7","status":"cancelled"}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No request with that id for this key's email.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`not_cancellable`: Already paid or under way.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cancel","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#cancel","description":"Docs. MCP tool: cancel_request"}}},"/api/v1/uploads":{"post":{"summary":"Upload a file (CAD, sequences, sample sheet, artwork); put the returned url in a spec field","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","required":["file"],"properties":{"file":{"type":"string","format":"binary"}}}}}},"responses":{"201":{"description":"Stored","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"filename":{"type":"string"},"size":{"type":"integer"},"url":{"type":"string"},"expires_at":{"type":"string","format":"date-time"}}},"example":{"object":"upload","id":"upl_Lm2nB7vC4xZ9","filename":"drawing.pdf","size":182044,"url":"https://midgardindustrial.aramous.com/f/…","expires_at":"2026-12-17T09:00:00.000Z"}}}},"400":{"description":"`invalid_request`: No `file` field. `invalid_file`: Empty, larger than 50 MB, or a type that is not accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"upload","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#upload","description":"Docs"}}},"/api/v1/webhook":{"get":{"summary":"This key's webhook endpoint","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"object":"webhook","url":null}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"webhookGet","tags":["Webhooks"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#webhook-get","description":"Docs"}},"put":{"summary":"Set the webhook endpoint; returns a new signing secret once","description":"Events for requests placed with this key: request.quoted, request.status_changed, request.message. Each POST carries `Webhook-Signature: t=<unix>,v1=<hex>` where v1 = HMAC-SHA256(secret, `${t}.${raw body}`).","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":["string","null"],"format":"uri","description":"An https address on a public host. null stops deliveries."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"object":"webhook","url":"https://example.com/hooks/orders","secret":"whsec_…"}}}},"400":{"description":"`invalid_request`: Not an https address on a public host.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"webhookPut","tags":["Webhooks"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#webhook-put","description":"Docs"}},"delete":{"summary":"Stop webhook deliveries","security":[{"bearer":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"object":"webhook","url":null}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"webhookDelete","tags":["Webhooks"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#webhook-delete","description":"Docs"}}},"/api/v1/quotes/{id}/accept":{"post":{"summary":"Accept a quote and say how you continue","description":"`continue: \"midgard\"` keeps the order here: send `terms_name`, the name of the person accepting the order terms (see /terms). A 1% platform fee is added as its own line. Without `po` the answer carries `payment_url` for the first card payment; with `po` each payment is invoiced. `continue: \"own\"` takes the quote to the supplier on your own, free: your contact details go to the supplier and theirs appear on the request's timeline. The same as the `choose_managed` and `choose_direct` actions.","security":[{"bearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["continue","terms_name"],"properties":{"continue":{"type":"string","enum":["midgard"]},"terms_name":{"type":"string","minLength":2,"maxLength":120,"description":"The name of the person accepting the order terms"},"po":{"type":"string","maxLength":80,"description":"Purchase order number. With one, payments are invoiced."},"billing_email":{"type":"string","format":"email","description":"Where invoices go, if not the key's email"},"revision":{"type":"string","maxLength":20,"description":"Parts: the file revision the order is built to, e.g. Rev C"}}},{"type":"object","required":["continue"],"properties":{"continue":{"type":"string","enum":["own"]}}}]},"examples":{"keep":{"summary":"Keep the order here","value":{"continue":"midgard","terms_name":"Ada Lovelace"}},"own":{"summary":"Continue on your own","value":{"continue":"own"}}}}}},"responses":{"200":{"description":"The quote, with `continue` as sent. `midgard`: status `accepted` and `payment_url`. `own`: `supplier`, the supplier's name.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Quote"},{"type":"object","properties":{"continue":{"type":"string","enum":["midgard","own"]},"supplier":{"type":["string","null"]}}}]},"example":{"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"}}}},"400":{"description":"`invalid_request`: No `continue`, no `terms_name` for \"midgard\", or the quote can no longer be accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: No key, or a key that is wrong or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: No quote with that id on this email's requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: More than 120 calls a minute with this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"`server_error`: The quote could not be accepted; check the request before retrying.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"acceptQuote","tags":["Requests"],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers/api#accept-quote","description":"Docs. MCP tool: accept_quote"}}}},"tags":[{"name":"Directory","description":"Search and read listings. No key needed."},{"name":"Keys","description":"Sign in by a code sent by email and manage keys."},{"name":"Requests","description":"Requests for quotes, quotes, orders, messages and files."},{"name":"Webhooks","description":"Callbacks when a request changes."}],"externalDocs":{"url":"https://midgardindustrial.aramous.com/developers","description":"Developer docs, quick starts and MCP setup"}}