Compliance

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

POST /compliance/path

Return a product-specific planning table of possible certification requirements and an optional draft explanation.

Required scope: compliance:read.

Authentication: bearer key.

Field	Type	Required	Details
product	string	Yes	Min length 2. Max length 400
markets	string[]	No	Max items 10. Default: [“US”]
radios	string[]	No	Max items 10
moduleIsPreCertified	boolean,null	No
battery	string	No	One of: none, liion_contained, liion_pack, other. Default: “none”
mainsPowered	boolean	No
laser	boolean	No
childrensProduct	boolean	No
medical	boolean	No
explain	boolean	No	Request an optional generated explanation of the deterministic table.

200 response schema

{
  "type": "object",
  "properties": {
    "requirements": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "mark": {
            "type": "string"
          },
          "market": {
            "type": "string"
          },
          "applies": {
            "type": "string",
            "enum": [
              "yes",
              "likely",
              "confirm"
            ]
          },
          "path": {
            "type": "string"
          },
          "costUsdLow": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "costUsdHigh": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "weeksLow": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "weeksHigh": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "basis": {
            "type": "string"
          },
          "responsibleParty": {
            "type": "string"
          }
        },
        "required": [
          "mark",
          "market",
          "applies",
          "path",
          "costUsdLow",
          "costUsdHigh",
          "weeksLow",
          "weeksHigh",
          "basis",
          "responsibleParty"
        ]
      }
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "explanation": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "explanationNote": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "draft": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "note": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "requirements",
    "notes",
    "explanation",
    "explanationNote",
    "draft",
    "note",
    "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 /compliance/hts-candidates

Return candidate tariff headings with reasoning and sources. No final classification is selected.

Required scope: compliance:read.

Authentication: bearer key.

Field	Type	Required	Details
product	string	Yes	Min length 2. Max length 200
description	string	Yes	Min length 2. Max length 2000
materials	string	No	Max length 400
function	string	No	Max length 400

200 response schema

{
  "type": "object",
  "properties": {
    "categoriesMatched": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "candidates": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "reasoning": {
            "type": "string"
          },
          "mfnRatePct": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ]
          },
          "section301": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "confidence": {
            "type": "string",
            "const": "candidate"
          }
        },
        "required": [
          "code",
          "description",
          "reasoning",
          "mfnRatePct",
          "section301",
          "sources",
          "confidence"
        ]
      }
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "chosen": {
      "type": "null"
    },
    "note": {
      "type": "string"
    },
    "requestId": {
      "type": "string"
    }
  },
  "required": [
    "categoriesMatched",
    "candidates",
    "notes",
    "chosen",
    "note",
    "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.

Response models

Error