{"openapi":"3.1.0","info":{"title":"Material Transition API","version":"2.0.0","summary":"The developer platform for the global sustainable-materials atlas.","description":"Search and compare sustainable materials, discover substitutes for legacy plastics, map verified suppliers and their production footprints, and pull regional emissions data — all from one unified atlas aggregated from 10+ fragmented industry sources.\n\n> **Mock preview.** This is a scaffolded preview. Responses are representative fixtures; production payloads are served from the live Supplier Intelligence database.","contact":{"name":"Material Transition","url":"https://materialtransition.com"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://api.materialtransition.com","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Authentication","description":"Verify and inspect the calling API key."},{"name":"System","description":"Health and metadata."},{"name":"Materials","description":"The materials atlas — properties, sustainability, substitutes."},{"name":"Suppliers","description":"Verified suppliers and their production footprints."},{"name":"Search","description":"Unified hybrid search across the atlas."},{"name":"Emissions","description":"Regional emissions data (Climate TRACE aligned)."},{"name":"Regulatory","description":"Material regulatory status by jurisdiction."}],"paths":{"/v1/me":{"get":{"tags":["Authentication"],"summary":"Who am I","description":"Returns the account, plan, scopes, and rate limits tied to the calling API key. Use it to verify credentials.","operationId":"getMe","responses":{"200":{"description":"The authenticated identity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Identity"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/rate-limit":{"get":{"tags":["Authentication"],"summary":"Rate-limit status","description":"Returns the current rate-limit budget for the calling key — limit, used, remaining, and reset times. Also mirrored in the `X-RateLimit-*` response headers.","operationId":"getRateLimit","responses":{"200":{"description":"Current rate-limit budget.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimit"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/usage":{"get":{"tags":["Authentication"],"summary":"Usage summary","description":"API usage for the calling key over the current period, broken down by endpoint and status class.","operationId":"getUsage","parameters":[{"name":"period","in":"query","description":"Window to summarize.","schema":{"type":"string","enum":["day","month"],"default":"month"}}],"responses":{"200":{"description":"Usage summary.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/materials":{"get":{"tags":["Materials"],"summary":"List & search materials","operationId":"listMaterials","parameters":[{"name":"q","in":"query","description":"Full-text search across name, aliases, description.","schema":{"type":"string"}},{"name":"category","in":"query","description":"Filter by material category.","schema":{"type":"string"}},{"name":"min_sustainability","in":"query","description":"Minimum sustainability score (0–100).","schema":{"type":"integer"}},{"name":"biodegradable","in":"query","description":"Filter to biodegradable materials.","schema":{"type":"boolean"}},{"name":"sort","in":"query","description":"Sort field.","schema":{"type":"string","enum":["sustainability","name","supplier_count"],"default":"sustainability"}},{"name":"page","in":"query","description":"1-indexed page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Results per page (max 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"A page of materials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MaterialList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/materials/{id}":{"get":{"tags":["Materials"],"summary":"Get a material","operationId":"getMaterial","parameters":[{"name":"id","in":"path","required":true,"description":"Material slug, e.g. `polylactic-acid`.","schema":{"type":"string"}}],"responses":{"200":{"description":"The material.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Material"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/materials/{id}/substitutes":{"get":{"tags":["Materials"],"summary":"Find sustainable substitutes","description":"Returns ranked sustainable alternatives to the given material, scored by property similarity and sustainability uplift.","operationId":"getMaterialSubstitutes","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","description":"Max substitutes to return.","schema":{"type":"integer","default":5,"maximum":20}}],"responses":{"200":{"description":"Ranked substitutes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubstituteList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/materials/compare":{"post":{"tags":["Materials"],"summary":"Compare materials","description":"Compare two or more materials side by side across properties and sustainability metrics.","operationId":"compareMaterials","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["ids"],"properties":{"ids":{"type":"array","items":{"type":"string"},"minItems":2,"example":["polylactic-acid","recycled-pet"]}}}}}},"responses":{"200":{"description":"Comparison matrix.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Comparison"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/suppliers":{"get":{"tags":["Suppliers"],"summary":"List & search suppliers","operationId":"listSuppliers","parameters":[{"name":"q","in":"query","description":"Search supplier names.","schema":{"type":"string"}},{"name":"material","in":"query","description":"Filter to suppliers offering this material slug.","schema":{"type":"string"}},{"name":"region","in":"query","description":"Filter by region.","schema":{"type":"string"}},{"name":"verified","in":"query","description":"Only verified suppliers.","schema":{"type":"boolean"}},{"name":"certification","in":"query","description":"Filter by certification.","schema":{"type":"string"}},{"name":"page","in":"query","description":"1-indexed page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Results per page (max 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"A page of suppliers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupplierList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/suppliers/{id}":{"get":{"tags":["Suppliers"],"summary":"Get a supplier","description":"Returns the supplier plus its full production footprint.","operationId":"getSupplier","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"The supplier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Supplier"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/search":{"get":{"tags":["Search"],"summary":"Unified hybrid search","description":"Searches across materials and suppliers in one call, returning typed, ranked results — the same hybrid (semantic + keyword) ranking the platform uses internally.","operationId":"search","parameters":[{"name":"q","in":"query","required":true,"description":"Natural-language or keyword query.","schema":{"type":"string"},"example":"marine biodegradable packaging"},{"name":"type","in":"query","description":"Restrict to one result type.","schema":{"type":"string","enum":["material","supplier"]}},{"name":"page","in":"query","description":"1-indexed page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Results per page (max 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Ranked, typed results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchList"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/emissions":{"get":{"tags":["Emissions"],"summary":"Emissions by region","description":"Regional greenhouse-gas emissions rollups by Climate TRACE sector.","operationId":"listEmissions","parameters":[{"name":"region","in":"query","schema":{"type":"string"}},{"name":"country","in":"query","schema":{"type":"string"}},{"name":"sector","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","description":"1-indexed page number.","schema":{"type":"integer","minimum":1,"default":1}},{"name":"per_page","in":"query","description":"Results per page (max 100).","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}],"responses":{"200":{"description":"Emissions records.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmissionsList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/v1/regulatory/{material}":{"get":{"tags":["Regulatory"],"summary":"Regulatory status for a material","operationId":"getRegulatory","parameters":[{"name":"material","in":"path","required":true,"description":"Material slug.","schema":{"type":"string"}},{"name":"jurisdiction","in":"query","description":"Filter by jurisdiction, e.g. `US`, `EU`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Regulatory entries.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegulatoryList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/health":{"get":{"tags":["System"],"summary":"Health check","operationId":"health","security":[],"responses":{"200":{"description":"Service status.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key as a bearer token. Demo key: `mt_demo_1234567890abcdef1234567890abcdef`."}},"responses":{"Unauthorized":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Resource not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"BadRequest":{"description":"Invalid request parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Sustainability":{"type":"object","properties":{"score":{"type":"integer","description":"0–100 composite sustainability score."},"biobased_pct":{"type":"number"},"recyclable":{"type":"boolean"},"biodegradable":{"type":"boolean"},"carbon_kg_co2e_per_kg":{"type":"number","description":"Cradle-to-gate carbon intensity."}}},"Material":{"type":"object","properties":{"id":{"type":"string","example":"polylactic-acid"},"name":{"type":"string","example":"Polylactic Acid (PLA)"},"category":{"type":"string","example":"Biopolymers"},"aliases":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"sustainability":{"$ref":"#/components/schemas/Sustainability"},"properties":{"type":"object","additionalProperties":true},"regulatory_flags":{"type":"array","items":{"type":"string"}},"supplier_count":{"type":"integer"},"updated_at":{"type":"string","format":"date-time"}}},"Substitute":{"type":"object","properties":{"material":{"$ref":"#/components/schemas/Material"},"similarity":{"type":"number","description":"0–1 property similarity to the source material."},"sustainability_uplift":{"type":"integer","description":"Δ sustainability score vs. the source."},"rationale":{"type":"string"}}},"ProductionSite":{"type":"object","properties":{"country":{"type":"string"},"region":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"},"capacity_tonnes_year":{"type":"integer"}}},"Supplier":{"type":"object","properties":{"id":{"type":"string","example":"sup_natureworks"},"name":{"type":"string"},"country":{"type":"string"},"region":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"},"materials":{"type":"array","items":{"type":"string"}},"certifications":{"type":"array","items":{"type":"string"}},"capacity_tonnes_year":{"type":"integer"},"verified":{"type":"boolean"},"match_strength":{"type":"string","enum":["NONE","BASIC","GOOD","STRONG"]},"website":{"type":"string","format":"uri"},"production_sites":{"type":"array","items":{"$ref":"#/components/schemas/ProductionSite"}},"updated_at":{"type":"string","format":"date-time"}}},"EmissionsRecord":{"type":"object","properties":{"region":{"type":"string"},"country":{"type":"string"},"sector":{"type":"string"},"emissions_mt_co2e":{"type":"number"},"year":{"type":"integer"},"trend_pct":{"type":"number"}}},"RegulatoryEntry":{"type":"object","properties":{"material":{"type":"string"},"jurisdiction":{"type":"string"},"status":{"type":"string","enum":["approved","restricted","banned","under-review"]},"regulation":{"type":"string"},"effective_date":{"type":"string","format":"date"},"notes":{"type":"string"}}},"SearchResult":{"type":"object","properties":{"type":{"type":"string","enum":["material","supplier"]},"id":{"type":"string"},"title":{"type":"string"},"subtitle":{"type":"string"},"score":{"type":"number","description":"Hybrid relevance score."}}},"Comparison":{"type":"object","properties":{"materials":{"type":"array","items":{"$ref":"#/components/schemas/Material"}},"metrics":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"Health":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"version":{"type":"string"},"mode":{"type":"string","example":"mock"},"timestamp":{"type":"string","format":"date-time"}}},"Identity":{"type":"object","properties":{"id":{"type":"string","example":"acct_demo"},"name":{"type":"string","example":"Demo Account"},"email":{"type":["string","null"],"format":"email"},"organization":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}}},"plan":{"type":"string","enum":["demo","sandbox","developer","production"]},"scopes":{"type":"array","items":{"type":"string"},"example":["materials:read","suppliers:read"]},"rate_limit":{"type":"object","properties":{"per_minute":{"type":"integer"},"per_day":{"type":"integer"}}},"key":{"type":"object","properties":{"prefix":{"type":"string","example":"mt_demo"},"last4":{"type":"string","example":"cdef"},"active":{"type":"boolean"}}},"authenticated":{"type":"boolean","example":true}}},"RateLimit":{"type":"object","properties":{"plan":{"type":"string","example":"demo"},"limit":{"type":"object","properties":{"per_minute":{"type":"integer"},"per_day":{"type":"integer"}}},"remaining":{"type":"object","properties":{"per_minute":{"type":"integer"},"per_day":{"type":"integer"}}},"used":{"type":"object","properties":{"per_minute":{"type":"integer"},"per_day":{"type":"integer"}}},"reset":{"type":"object","properties":{"minute":{"type":"string","format":"date-time"},"day":{"type":"string","format":"date-time"}}}}},"Usage":{"type":"object","properties":{"plan":{"type":"string"},"period":{"type":"object","properties":{"window":{"type":"string","enum":["day","month"]},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}}},"total_requests":{"type":"integer"},"requests_today":{"type":"integer"},"by_endpoint":{"type":"array","items":{"type":"object","properties":{"endpoint":{"type":"string"},"method":{"type":"string"},"count":{"type":"integer"}}}},"by_status":{"type":"object","additionalProperties":{"type":"integer"}},"avg_response_time_ms":{"type":"integer"}}},"Pagination":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"not_found"},"message":{"type":"string"},"status":{"type":"integer","example":404}}}}},"MaterialList":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Material"}}}}]},"SubstituteList":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Substitute"}}}}]},"SupplierList":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Supplier"}}}}]},"EmissionsList":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmissionsRecord"}}}}]},"RegulatoryList":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RegulatoryEntry"}}}}]},"SearchList":{"allOf":[{"$ref":"#/components/schemas/Pagination"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"}}}}]}}}}