API Reference

Access materialref.com data programmatically. Retrieve materials, equivalents, compositions, properties, and comparisons via our REST API.

Get your API key Manage API keys

Authentication

All API requests require an API key sent via the Authorization header. API keys are available on the Team plan.

Authorization: Bearer mref_your_api_key_here

Rate limits: Included in the response headers.

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997

Base URL

https://materialref.com/api/v1

All responses are JSON. Successful responses return 200. Errors return 401, 404, or 429 with an error message.

GET

List Materials

Retrieve a paginated list of published materials. Optionally filter by category.

/api/v1/materials

Parameters

Name	Type	Required	Description
category	string	optional	Filter by category (e.g. alloy_steel, stainless, carbon_steel)
page	integer	optional	Page number (default: 1)
limit	integer	optional	Results per page, max 100 (default: 20)

Example Request

curl "https://materialref.com/api/v1/materials?category=alloy_steel&page=1&limit=5" \
  -H "Authorization: Bearer mref_your_api_key"

Example Response

{
  "data": [
    {
      "slug": "42crmo4",
      "name": "42CrMo4",
      "number": "1.7225",
      "category": "alloy_steel",
      "subcategory": "quenched_tempered",
      "description": "Chromium-molybdenum alloy steel..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 142,
    "pages": 29
  }
}

GET

Get Material

Retrieve complete material data including equivalents, compositions (grouped by standard), properties (grouped by condition), and heat treatments.

/api/v1/materials/:slug

Parameters

Name	Type	Required	Description
slug	string	required	Material slug (URL path parameter)

Example Request

curl "https://materialref.com/api/v1/materials/42crmo4" \
  -H "Authorization: Bearer mref_your_api_key"

Example Response

{
  "data": {
    "slug": "42crmo4",
    "name": "42CrMo4",
    "number": "1.7225",
    "category": "alloy_steel",
    "equivalents": [
      {
        "standard_system": "ASTM",
        "country_code": "US",
        "grade_name": "AISI 4140",
        "match_percentage": 97
      }
    ],
    "compositions": {
      "EN 10083-3": [
        { "element": "C", "min_pct": 0.38, "max_pct": 0.45 },
        { "element": "Cr", "min_pct": 0.90, "max_pct": 1.20 }
      ]
    },
    "properties": {
      "QT": [
        { "property_name": "Tensile strength", "min_value": 900, "max_value": 1100, "unit": "MPa" }
      ]
    },
    "heat_treatments": [...]
  }
}

GET

Get Composition

Retrieve chemical composition data grouped by standard system.

/api/v1/materials/:slug/composition

Parameters

Name	Type	Required	Description
slug	string	required	Material slug

Example Request

curl "https://materialref.com/api/v1/materials/42crmo4/composition" \
  -H "Authorization: Bearer mref_your_api_key"

Example Response

{
  "data": {
    "EN 10083-3": [
      { "element": "C", "min_pct": 0.38, "max_pct": 0.45, "source_norm": "EN 10083-3:2006" },
      { "element": "Si", "min_pct": null, "max_pct": 0.40 },
      { "element": "Mn", "min_pct": 0.60, "max_pct": 0.90 }
    ]
  }
}

GET

Get Properties

Retrieve mechanical properties grouped by condition (e.g. QT, Normalized, Annealed).

/api/v1/materials/:slug/properties

Parameters

Name	Type	Required	Description
slug	string	required	Material slug

Example Request

curl "https://materialref.com/api/v1/materials/42crmo4/properties" \
  -H "Authorization: Bearer mref_your_api_key"

Example Response

{
  "data": {
    "QT": [
      { "property_name": "Tensile strength", "min_value": 900, "max_value": 1100, "unit": "MPa" },
      { "property_name": "Yield strength", "min_value": 650, "max_value": null, "unit": "MPa" }
    ],
    "Annealed": [
      { "property_name": "Hardness", "min_value": null, "max_value": 241, "unit": "HB" }
    ]
  }
}

GET

Compare Materials

Side-by-side comparison of two materials. Returns composition overlap analysis and compatibility verdict.

/api/v1/compare/:slug1/:slug2

Parameters

Name	Type	Required	Description
slug1	string	required	First material slug
slug2	string	required	Second material slug

Example Request

curl "https://materialref.com/api/v1/compare/42crmo4/aisi-4140" \
  -H "Authorization: Bearer mref_your_api_key"

Example Response

{
  "data": {
    "material_a": { "slug": "42crmo4", "name": "42CrMo4", "number": "1.7225" },
    "material_b": { "slug": "aisi-4140", "name": "AISI 4140", "number": "G41400" },
    "composition_comparison": [
      { "element": "C", "a": { "min": 0.38, "max": 0.45 }, "b": { "min": 0.38, "max": 0.43 }, "overlap": "full" },
      { "element": "Cr", "a": { "min": 0.90, "max": 1.20 }, "b": { "min": 0.80, "max": 1.10 }, "overlap": "partial" }
    ],
    "verdict": {
      "result": "compatible",
      "overlap_ratio": 85,
      "total_elements": 7,
      "full_overlap_elements": 6
    }
  }
}

GET

Search Materials

Full-text search across material names, numbers, and equivalent grades.

/api/v1/search

Parameters

Name	Type	Required	Description
q	string	required	Search query (min 2 characters)
limit	integer	optional	Max results, max 50 (default: 10)

Example Request

curl "https://materialref.com/api/v1/search?q=42CrMo4&limit=5" \
  -H "Authorization: Bearer mref_your_api_key"

Example Response

{
  "data": [
    {
      "slug": "42crmo4",
      "name": "42CrMo4",
      "number": "1.7225",
      "category": "alloy_steel",
      "top_equivalents": [
        { "grade_name": "AISI 4140", "standard_system": "ASTM" },
        { "grade_name": "SCM440", "standard_system": "JIS" }
      ]
    }
  ],
  "query": "42CrMo4"
}

Error Codes

Code	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — invalid or missing API key
404	Not found — material does not exist
429	Rate limit exceeded — wait and retry
500	Internal server error

{
  "error": "Invalid API key",
  "code": 401
}