Factory network
Base URL: https://app.trymaglev.com/api/v1. All endpoint families.
GET /factories
Section titled “GET /factories”List the factories Maglev works with. Never carries contact details; at most 50 per page.
Required scope: network:read.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
q |
query | No | Free text over English and Chinese names, specialty, capabilities, city and directory id |
process |
query | No | One manufacturing process, for example cnc, pcba, injection_molding |
city |
query | No | |
region |
query | No | |
startupFriendly |
query | No | yes |
answeredUs |
query | No | true: only factories that have answered Maglev |
minQuantityAtMost |
query | No | Only factories whose stated minimum for the process is at most this |
confidence |
query | No | verified, reported or unverified |
page |
query | No | |
pageSize |
query | No | Maximum 50 |
includeQuarantined |
query | No | Maglev keys only |
200 response schema
{ "type": "object", "properties": { "factories": { "type": "array", "items": { "$ref": "#/components/schemas/FactoryListItem" } }, "page": { "type": "integer" }, "pageSize": { "type": "integer" }, "total": { "type": "integer" }, "importedThrough": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. See recovery guidance.
GET /factories/search
Section titled “GET /factories/search”Alias of GET /factories with q.
Required scope: network:read.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
q |
query | Yes |
200 response schema
{ "type": "object", "properties": { "requestId": { "type": "string" } }}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. See recovery guidance.
GET /factories/{id}
Section titled “GET /factories/{id}”One factory by uuid or directory id. Customers receive selected manufacturing fields. Production keys with contacts:read also receive normalized business contacts; each such read is audited and capped at 300 per key per day. Raw directory, source, verification and interaction notes require a live internal maglev:* key.
Required scope: network:read.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes | uuid or mfg-, int-, or eng- directory id, such as mfg-sz-robotics-001 |
200 response schema
{ "type": "object", "properties": { "factory": { "type": "object", "properties": { "contacts": { "anyOf": [ { "type": "object", "properties": { "contactName": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactEmail": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactPhone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactWechat": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "directoryFields": { "type": "object", "properties": {} } } }, { "type": "null" } ] }, "contactsNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "whatTheyToldUs": { "type": "object", "properties": { "answeredSummary": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "contactedNote": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "communityComments": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastAnsweredAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sources": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } }, "directoryFields": { "type": "object", "properties": {} }, "certifications": { "type": "array", "items": { "type": "object", "properties": {} } } } } }}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. See recovery guidance.
GET /factories/{id}/interactions
Section titled “GET /factories/{id}/interactions”Raw internal mail threads and call notes for a factory. Requires a live internal maglev:* key and is audited. Customer and sandbox keys cannot read this shared correspondence, including snippets and summaries; the legacy interactions:read scope does not grant access.
Required scope: maglev:*.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes | |
bodies |
query | No | true to include message bodies (max 20 messages) |
transcripts |
query | No | true to include call transcripts |
200 response schema
{ "type": "object", "properties": { "threads": { "type": "array", "items": { "type": "object", "properties": { "subject": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "firstMessageAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "lastMessageAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "messageCount": { "type": "integer" }, "hasReply": { "type": "boolean" }, "participants": { "type": "array", "items": { "type": "string" } }, "messages": { "type": "array", "items": { "type": "object", "properties": { "senderDomain": { "type": "string" }, "sentAt": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "body": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } } } } }, "callNotes": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "createdAtSource": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "participants": { "type": "array", "items": { "type": "string" } }, "usable": { "type": "string" }, "summaryMarkdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "transcriptText": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } } } }, "directoryNotes": { "type": "object", "properties": {} }, "importedThrough": { "anyOf": [ { "type": "string", "description": "Last refresh of the mail mirror" }, { "type": "null" } ] }, "coverageNote": { "type": "string" } }}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. See recovery guidance.
GET /network/summary
Section titled “GET /network/summary”Counts of the network visible to this key: total, by process, by region, answered us, with certifications.
Required scope: network:read.
Authentication: bearer key.
200 response schema
{ "type": "object", "properties": { "total": { "type": "integer" }, "byProcess": { "type": "object", "properties": {} }, "byRegion": { "type": "object", "properties": {} }, "answeredUs": { "type": "integer" }, "withCertifications": { "type": "integer" }, "importedThrough": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }}Errors: 400 Validation error; 401 Missing or invalid key; 403 Scope or mode does not allow this; 404 Not found; 429 Rate limit reached. See recovery guidance.