REST API

API Reference

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

Get your API key View plans

Authentication

All API requests require an API key sent via the Authorization header. API keys are available on Team and API plans. Generate keys in your account settings.

Authorization: Bearer mref_your_api_key_here

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.

Rate Limits

Rate limit information is included in every API response as headers.

Plan	Limit
API	500 requests / day
Team	1,000 requests / day

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 997
X-RateLimit-Reset: 2026-03-20T00:00:00Z

Endpoints

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"
}

Code Examples

JSJavaScript / Node.js

const response = await fetch(
  "https://materialref.com/api/v1/materials/42crmo4",
  {
    headers: {
      Authorization: "Bearer mref_your_api_key",
    },
  }
);

const { data } = await response.json();
console.log(data.name);             // "42CrMo4"
console.log(data.equivalents[0]);   // { grade_name: "AISI 4140", ... }

PYPython

import requests

response = requests.get(
    "https://materialref.com/api/v1/materials/42crmo4",
    headers={"Authorization": "Bearer mref_your_api_key"},
)

data = response.json()["data"]
print(data["name"])                # 42CrMo4
print(data["equivalents"][0])      # {"grade_name": "AISI 4140", ...}

SHcurl

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

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
}

Ready to integrate?

Get your API key and start querying material data in minutes.

Get your API key View pricing