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 (Maglev session).

Authentication: browser session.

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.

POST /capabilities/{id}/review

Publish a reviewed capability (Maglev session).

Authentication: browser session.

Parameter	Location	Required	Details
`id`	path	Yes

Field	Type	Required	Details
`publish`	boolean	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.

POST /run

Save a quote request against a capability. Requires Idempotency-Key. Never places an order.

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.

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 · Run · RunInput · RunOutput