Capabilities and requests

Base URL: https://app.trymaglev.com/api/v1. All endpoint families.

POST /discover

Rank interview backed capabilities for a request. Sandbox data is synthetic.

Required scope: discover.

Authentication: bearer key.

Field	Type	Required	Details
`query`	string	Yes	Min length 1. Max length 500
`quantity`	integer	No	Minimum 1. Maximum 10000000
`optimize`	string	No	One of: cost, speed
`process`	string	No	One of: cnc, pcba, injection_molding, sheet_metal, 3d_printing, wire_harness, assembly, testing
`material`	string	No
`country`	string	No
`maxLeadTimeDays`	integer	No	Minimum 1
`maxUnitPriceUsd`	number	No	Greater than 0
`limit`	integer	No	Minimum 1. Maximum 30

200 response schema

{
  "type": "object",
  "properties": {
    "mode": {
      "type": "string",
      "enum": [
        "sandbox",
        "live"
      ]
    },
    "results": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Match"
      }
    },
    "count": {
      "type": "integer"
    },
    "pricingNote": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "mode",
    "results",
    "count",
    "pricingNote",
    "requestId"
  ]
}

Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 429 Rate limit reached; 500 Server failure. See recovery guidance.

POST /inspect

One capability with its input schema and non binding pricing.

Required scope: inspect.

Authentication: bearer key.

Field	Type	Required	Details
`capabilityId`	string	Yes	Max length 100

200 response schema

{
  "type": "object",
  "properties": {
    "capability": {
      "$ref": "#/components/schemas/Capability"
    },
    "inputSchema": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string"
        },
        "required": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "properties": {
          "type": "object",
          "additionalProperties": {
            "type": "object"
          }
        }
      },
      "required": [
        "type",
        "required",
        "properties"
      ]
    },
    "execution": {
      "type": "string"
    },
    "requiredFiles": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "pricing": {
      "type": "object",
      "properties": {
        "currency": {
          "type": "string",
          "const": "USD"
        },
        "unitPrice": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "setupPrice": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "maglevFee": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "shippingAndTaxes": {
          "anyOf": [
            {
              "type": "number"
            },
            {
              "type": "null"
            }
          ]
        },
        "binding": {
          "type": "boolean",
          "const": false
        }
      },
      "required": [
        "currency",
        "unitPrice",
        "setupPrice",
        "maglevFee",
        "shippingAndTaxes",
        "binding"
      ]
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "capability",
    "inputSchema",
    "execution",
    "requiredFiles",
    "pricing",
    "requestId"
  ]
}

GET /capabilities

The catalog visible to this key.

Required scope: discover.

Authentication: bearer key.

200 response schema

{
  "type": "object",
  "properties": {
    "capabilities": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Capability"
      }
    },
    "mode": {
      "type": "string",
      "enum": [
        "sandbox",
        "live"
      ]
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "capabilities",
    "mode",
    "requestId"
  ]
}

Errors: 401 Invalid key or missing sign-in; 403 Insufficient access; 429 Rate limit reached; 500 Server failure. See recovery guidance.

GET /review-queue

Self reported live capabilities awaiting Maglev review, at most 100. Needs a bearer key and a Maglev session belonging to Maglev’s own organisation; either one alone is refused.

Authentication: bearer key + browser session.

200 response schema

{
  "type": "object",
  "properties": {
    "capabilities": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/CapabilityRecord"
      }
    },
    "requestId": {
      "type": "string",
      "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request."
    }
  },
  "required": [
    "requestId"
  ]
}

Errors: 400 Validation error; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.

POST /capabilities/{id}/review

Publish a reviewed capability. Needs a bearer key and a Maglev session belonging to Maglev’s own organisation; either one alone is refused.

Authentication: bearer key + browser session.

Parameter	Location	Required	Details
`id`	path	Yes

Field	Type	Required	Details
`publish`	boolean	Yes

200 response schema

{
  "type": "object",
  "properties": {
    "capability": {
      "$ref": "#/components/schemas/CapabilityRecord"
    },
    "requestId": {
      "type": "string",
      "description": "Echoed in the X-Request-Id response header. Quote it to Maglev when asking what became of a request."
    }
  },
  "required": [
    "requestId"
  ]
}

Errors: 400 Validation error. A body is read here, so one of five codes rides on this status and none is retryable unchanged. validation_error: the body parsed and failed the schema, and details names each path. invalid_json: there was no body, or it was not valid UTF-8 JSON. invalid_text: a string or property name holds a NUL or an unpaired Unicode surrogate, which storage cannot keep, so correct the source text. duplicate_key: a JSON object repeats a property name, no path is given, and the conflicting fields have to be resolved at the source. invalid_number: a number is outside the range that survives the round trip, so quote large identifiers as strings. Nothing was written in any of them.; 401 unauthorized: no bearer key was presented, or the one presented is unknown, expired or revoked. Present a valid key; nothing was done.; 403 Scope or mode does not allow this. On scope_required, details.obtainable says whether a key that carries the scope can be issued at all: true means reissuing this key with the scope would work, false means no key of this kind can ever carry it, because contacts:read and approvals:write are granted on live mode alone and maglev:* belongs to Maglev’s own keys. Stored scopes narrow the grant a mode and organisation already allow, so widening a key never adds one.; 404 Not found; 413 body_too_large: the request body exceeds this operation’s limit, and it was not read to the end. Send less in one request rather than repeating it; 415 content_type: the request did not declare application/json, so no body was read and nothing was written. Set the header and send it again; 429 rate_limit: a limit for this key or route is spent. details.retryAfter is how many whole seconds of the refused window remain, at least 1, and the Retry-After header carries the same number. Wait that long rather than assuming a minute; the windows here range from 60 to 86400 seconds. Nothing was done.; 500 internal_error: the request did not complete and the reason was not one this API anticipates. Whether anything was written is unknown. Read error.message, which carries what is safe to do next, and quote the X-Request-Id header to Maglev; the request id is in the body too. Where an operation takes an Idempotency-Key, repeating the request with the same key is the way to learn the earlier outcome without running the work twice, unless the message says to use a new one.. See recovery guidance.

POST /run

Save a quote request against a capability. Requires Idempotency-Key. Never places an order. A first request answers 201 and a replay of the same key answers 200; both are success.

Saves a quote request only. New requests return 201; identical idempotent replays return 200. Does not dispatch to suppliers, place orders, charge money or certify a product.

Required scope: runs:own.

Authentication: bearer key.

Parameter	Location	Required	Details
`Idempotency-Key`	header	Yes

Field	Type	Required	Details
`capabilityId`	string	Yes	Max length 100
`input`	object	Yes
`input.quantity`	integer	If parent supplied	Minimum 1. Maximum 10000000
`input.specification`	string	If parent supplied	Min length 10. Max length 4000

200 response schema

{
  "type": "object",
  "properties": {
    "run": {
      "$ref": "#/components/schemas/Run"
    },
    "replayed": {
      "type": "boolean",
      "const": true
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "run",
    "replayed",
    "requestId"
  ]
}

201 response schema

{
  "type": "object",
  "properties": {
    "run": {
      "$ref": "#/components/schemas/Run"
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "run",
    "requestId"
  ]
}

Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 404 Endpoint or record unavailable; 409 Version, publication or idempotency conflict; 422 Missing facts, turn limit or quantity below MOQ; 429 Rate limit reached; 500 Server failure. See recovery guidance.

GET /runs

Your saved runs, newest first, at most 50.

Required scope: runs:own.

Authentication: bearer key.

200 response schema

{
  "type": "object",
  "properties": {
    "runs": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/Run"
      }
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "runs",
    "requestId"
  ]
}

Errors: 401 Invalid key or missing sign-in; 403 Insufficient access; 429 Rate limit reached; 500 Server failure. See recovery guidance.

GET /runs/{id}

One run.

Required scope: runs:own.

Authentication: bearer key.

Parameter	Location	Required	Details
`id`	path	Yes

200 response schema

{
  "type": "object",
  "properties": {
    "run": {
      "$ref": "#/components/schemas/Run"
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "run",
    "requestId"
  ]
}

Response models

Match · Estimate · Error · Capability · CapabilityRecord · Facts · Run · RunInput · RunOutput