HTTP quickstart

This walkthrough saves one quote request using synthetic supplier data. It does not contact a manufacturer or place an order.

To try the CLI first without a key, use the local walkthrough.

1. Connect a sandbox key

Open API keys and create a sandbox key. Save it as MAGLEV_API_KEY in your local environment or secret manager. The secret is shown once and expires after 24 hours. Keep it out of chat, source control and logs.

Check the connection:

curl --fail-with-body https://app.trymaglev.com/api/v1/me \
  -H "Authorization: Bearer $MAGLEV_API_KEY"

The response includes the key’s id, mode, name, expiresAt and a requestId. Check that mode is sandbox.

2. Discover capabilities

curl --fail-with-body https://app.trymaglev.com/api/v1/discover \
  -H "Authorization: Bearer $MAGLEV_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"CNC aluminum enclosures","quantity":100,"country":"US","optimize":"speed"}'

results contains matching capabilities, reasons and non-binding factory estimates. The returned ID sample-cnc-us belongs to a synthetic US machining example. Select an ID from your actual response for the next step.

An empty list means the visible catalog has no known match. Keep your constraints and ask a useful follow-up; do not invent a supplier.

3. Inspect the selected capability

curl --fail-with-body https://app.trymaglev.com/api/v1/inspect \
  -H "Authorization: Bearer $MAGLEV_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"capabilityId":"sample-cnc-us"}'

Read inputSchema, requiredFiles, execution and pricing. Missing Maglev fees, freight and taxes are null, not zero. File requirements describe what a real quote needs; this endpoint does not upload the files.

4. Save the request

POST /run requires a unique Idempotency-Key. See idempotency and 409 conflicts.

curl --fail-with-body https://app.trymaglev.com/api/v1/run \
  -H "Authorization: Bearer $MAGLEV_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: enclosure-example-001' \
  --data '{"capabilityId":"sample-cnc-us","input":{"quantity":100,"specification":"Synthetic example: aluminum 6061 enclosures. US build required. Drawing revision A needs review; material substitutions require approval."}}'

The new request returns HTTP 201. run.id identifies the saved record; run.output.status is sandbox_complete and run.output.orderPlaced is false. Here, complete means the sandbox request was saved, not that a factory produced or quoted anything.

5. Retrieve it later

Replace RUN_ID with the ID returned above:

curl --fail-with-body https://app.trymaglev.com/api/v1/runs/RUN_ID \
  -H "Authorization: Bearer $MAGLEV_API_KEY"

If you retry step 4 with the same key and body, Maglev returns the original run with replayed: true. A changed body with that key returns HTTP 409.