canonical: https://jentic.com/apis/mpds.io/mpds # MPDS API The Materials Platform for Data Science (MPDS) API exposes the curated PAULING FILE materials database - crystal structures, phase diagrams, physical properties, and the underlying scientific literature references - as a programmatic feed. Materials scientists and machine learning teams use it to assemble training datasets and to retrieve experimentally validated property values without manual literature review. The API has four endpoints covering faceted search, phase-id and entry-id retrieval, and bulk download of structured data. ## For AI agents Query the curated MPDS materials science database for crystal structures, phase diagrams, and physical properties, returning experimentally validated entries with literature provenance. ## Scope Does not handle DFT calculation submission, lab notebook capture, or chemical synthesis planning - use for retrieving curated MPDS materials data only. ## Capabilities - Run faceted search across the MPDS database with element, property, and class filters via GET `/search/facet` - Retrieve a phase diagram entry by its phase_id via GET `/search/phase_id/{phaseId}` - Fetch a single curated entry - structure, property, or reference - by entryId via GET `/search/entry/{entryId}` - Download full datasets in CIF, JSON, or other formats by data type via GET `/download/s/{dataType}` - Retrieve the literature reference attached to each curated property value for provenance tracking ## Use cases ### Build a Curated Training Set for Materials ML Materials informatics teams pull experimentally measured property values - band gaps, formation enthalpies, lattice parameters - from MPDS to train predictive models on data with provenance, not first-principles guesses. The faceted search endpoint filters by element set, property type, and structural class so a clean dataset can be assembled without scraping primary literature. Example prompt: Call GET `/search/facet` with elements set to {Ga, As, In, P} and property = 'band gap', then for each hit call GET `/search/entry/{entryId}` to extract the measured value and citation. ### Phase Diagram Lookup for Alloy Design Alloy design and metallurgy teams need experimentally constructed phase diagrams to choose composition windows that avoid brittle intermetallic phases. MPDS exposes binary, ternary, and higher phase diagrams indexed by phase_id. Retrieving the diagram with `/search/phase_id/{phaseId}` returns the equilibrium phases, transition temperatures, and source references in one call. Example prompt: Find the Fe-Cr binary phase diagram by calling GET `/search/facet` with elements = 'Fe,Cr' and class = 'phase diagram', then GET `/search/phase_id/{phaseId}` on the matching id. ### Bulk Crystal Structure Download for DFT Pipelines Computational chemists feed thousands of experimentally observed crystal structures into DFT or molecular dynamics pipelines. The `/download/s/{dataType}` endpoint returns curated structure sets in batch, removing the need to iterate per-entry. A typical project pulls all cubic perovskite structures in one bulk call before running calculations. Example prompt: Call GET `/download/s/structures` with a filter for cubic perovskite class and persist the returned CIF archive to local storage. ### Agent-Driven Literature-Backed Property Lookup An AI research assistant answers a chemist's question - 'what is the measured melting point of TiB2?' - by searching MPDS through Jentic, retrieving the matching entry, and returning the value with its peer-reviewed citation. The four-endpoint surface is small enough that the agent reliably picks `/search/facet` for discovery and `/search/entry/{entryId}` for the property value. Example prompt: Search Jentic for 'find experimental property in mpds', load the facet schema, query for {TiB2, melting point}, and return the value plus literature reference from `/search/entry/{entryId}.` ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/search/facet` | Run faceted search across the MPDS catalogue | | GET | `/search/phase_id/{phaseId}` | Retrieve a phase diagram by phase_id | | GET | `/search/entry/{entryId}` | Fetch a single curated entry by entryId | | GET | `/download/s/{dataType}` | Bulk download structures or properties by data type | ## Key resources - **Faceted Search** — Element, property, and class filters across the MPDS catalogue - **Phase Diagram** — Binary, ternary, and higher equilibrium phase diagrams keyed by phase_id - **Entry** — Individual curated record - structure, property, or reference - keyed by entryId - **Bulk Download** — Batch export of structures and properties by data type ## Why Jentic - **Setup:** Wiring MPDS by hand means setting your key in the Key header, targeting the v0 host, and learning the PAULING FILE schema names behind its facet, phase, and entry lookups. Through Jentic you install once, import the MPDS API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** This spec is read-only materials retrieval, with phase and entry ids in the URL path, so limit the agent to the operations it needs, such as facet search or fetching one phase or entry. You choose the operations it may call, so it stays within these read lookups. - **Credential handling:** Your MPDS API key is stored once, encrypted, by your own Jentic One instance and injected into the Key header at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find a binary phase diagram', and Jentic returns the matching MPDS operation with its input schema across facet, phase_id, entry, and download, so the agent calls the right endpoint without learning the PAULING FILE schema names. ## Related APIs - **Google BigQuery API** — BigQuery hosts the Materials Project public dataset for SQL-style materials queries - **Snowflake API** — Snowflake serves as the warehouse backend for materials informatics teams loading MPDS exports - **Airbyte API** — Airbyte orchestrates ingestion pipelines that can schedule MPDS bulk downloads ## FAQ ### What authentication does the MPDS API use? The MPDS API uses an API key passed in the Key request header. Through Jentic the key is stored encrypted in the vault and the agent calls the operation without ever holding the raw secret. ### Can I download crystal structures in bulk? Yes. GET `/download/s/{dataType}` returns a batched archive for the selected data type - for example structures or phase diagrams - instead of paging through `/search/entry/{entryId}` one record at a time. ### What are the rate limits for the MPDS API? MPDS enforces per-account quotas tied to your subscription class and applies short-window throttling on `/search/facet` and `/download/s` endpoints. Run heavy enumerations against `/download/s` rather than scripting many `/search/entry` calls to stay inside quota. ### How do I fetch a phase diagram through Jentic? Search Jentic for 'find a binary phase diagram', load the search/facet schema, run a faceted search with the two element symbols and class = 'phase diagram', then call GET `/search/phase_id/{phaseId}` on the matching id. ### Is the MPDS API free? No. MPDS data is curated commercially. A limited evaluation tier exists but production use requires an MPDS subscription with corresponding API quota. ### Does every entry come with a literature reference? Yes. MPDS records originate from the PAULING FILE corpus, so `/search/entry/{entryId}` returns the source citation for the value, which is what makes the dataset suitable for provenance-sensitive workflows like regulatory submissions and ML training. ### Can I limit what my agent is allowed to do with the MPDS API? Yes. Because you run Jentic One yourself, your own rules decide which MPDS operations and which stored API key the agent may use, and the spec is read-only materials retrieval so nothing it calls can modify data. You can allow only the operations a task needs, such as faceted search on GET `/search/facet`, while withholding phase lookups on GET `/search/phase_id/{phaseId}`, single-entry reads on GET `/search/entry/{entryId}`, or bulk exports on GET `/download/s/{dataType}.` The agent stays inside those read lookups and cannot reach any operation you have not granted.