openapi: 3.1.0 info: title: Materials Project Defect Tasks Materials Thermo API description: "\nThe Materials Project API allows anyone to have direct access to current, up-to-date information from the Materials Project database in a structured way.\n\nThis allows for analysis, development of automated tools, machine learning, downloading personal copies of the Materials Project database and more on a large scale.\n\nThe API is offered with the hopes of making Materials Project data more useful to you. We want you to use our data! As such, the API is offered free-of-charge and we support several tools to help you get started.\n\n## API Key\nTo make any request to the Materials Project API, you must use an API key. Your API key is generated for you automatically upon registering with the Materials Project website and is synced with the email you used to register.\n\nRemember to keep your API key safe and to not share it with anyone you do not trust.\n\nIf you are logged in, you can always access your API key from this page or from your [dashboard](https://next-gen.materialsproject.org/dashboard).\n\nIf you intend heavy API usage, you can give us a heads up by sending a message to . With the exception of retrieving charge densities, this is not required, but may help us if we see unusual load on our servers.\n\n## Accessing Data\nTo use the API, you have three options:\n\n1. You can use our first-party supported Python client. This is the recommend route. The `mp-api` package containing the client is pip installable.\n\n ```\n pip install mp-api\n ```\n\n The `MPRester` client can be accessed by importing from it. This will ultimately replace the legacy `MPRester` available in pymatgen.\n\n For more details on how to use this, including code examples, please see .\n\n2. You can demo the API interactively on this documentation page. Click the \"Authorize\" button, paste in your API key, and then click the appropriate section to try out a query.\n\n3. Since this is a REST API, and offers a fully-compliant OpenAPI specification, it's possible to use the API with many libraries in many languages and environments, including JavaScript, MATLAB, Mathematica, etc. However, we do not offer first-party support for explaining how to do this, and you will have to follow the specification yourself.\n\n" version: 0.86.4rc5.dev1+g77c2c1315 x-logo: url: https://raw.githubusercontent.com/materialsproject/emmet/master/emmet-api/emmet/api/core/assets/mp_logo_small.png security: - ApiKeyAuth: [] tags: - name: Materials Thermo description: Route providing computed thermodynamic data for a material such as formation energy and energy above hull. Corrected energy values are also available that employ the schemes discussed by [Jain *et al.*](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.84.045115) and [Wang *et al.*](https://chemrxiv.org/engage/chemrxiv/article-details/60c758d9469df42a4ef45757) See the `ThermoDoc` schema for a full list of fields returned by this route. externalDocs: description: For a more detailed description url: https://docs.materialsproject.org/methodology/total-energies paths: /materials/thermo/: get: tags: - Materials Thermo summary: Get ThermoDoc documents operationId: search_materials_thermo__get parameters: - name: thermo_ids in: query required: false schema: anyOf: - type: string - type: 'null' description: Comma-separated list of thermo_id values to query on title: Thermo Ids description: Comma-separated list of thermo_id values to query on - name: material_ids in: query required: false schema: anyOf: - type: string - type: 'null' description: Comma-separated list of material_id values to query on title: Material Ids description: Comma-separated list of material_id values to query on - name: thermo_types in: query required: false schema: anyOf: - type: string - type: 'null' description: Comma-separated list of thermo_type values to query on title: Thermo Types description: Comma-separated list of thermo_type values to query on - name: formula in: query required: false schema: anyOf: - type: string - type: 'null' description: Query by formula including anonymized formula or by including wild cards. A comma delimited string list of anonymous formulas or regular formulas can also be provided. title: Formula description: Query by formula including anonymized formula or by including wild cards. A comma delimited string list of anonymous formulas or regular formulas can also be provided. - name: chemsys in: query required: false schema: anyOf: - type: string - type: 'null' description: A comma delimited string list of chemical systems. Wildcards for unknown elements only supported for single chemsys queries title: Chemsys description: A comma delimited string list of chemical systems. Wildcards for unknown elements only supported for single chemsys queries - name: is_stable in: query required: false schema: anyOf: - type: boolean - type: 'null' description: Whether the material is stable. title: Is Stable description: Whether the material is stable. - name: nsites_max in: query required: false schema: anyOf: - type: integer - type: 'null' description: Query for maximum value of nsites title: Nsites Max description: Query for maximum value of nsites - name: nsites_min in: query required: false schema: anyOf: - type: integer - type: 'null' description: Query for minimum value of nsites title: Nsites Min description: Query for minimum value of nsites - name: nsites in: query required: false schema: anyOf: - type: integer - type: 'null' description: Query for nsites being equal to an exact value title: Nsites description: Query for nsites being equal to an exact value - name: nsites_not_eq in: query required: false schema: anyOf: - type: integer - type: 'null' description: Query for nsites being not equal to an exact value title: Nsites Not Eq description: Query for nsites being not equal to an exact value - name: nsites_eq_any in: query required: false schema: type: string description: Query for nsites being any of these values. Provide a comma separated list. title: Nsites Eq Any description: Query for nsites being any of these values. Provide a comma separated list. - name: nsites_neq_any in: query required: false schema: type: string description: Query for nsites being not any of these values. Provide a comma separated list. title: Nsites Neq Any description: Query for nsites being not any of these values. Provide a comma separated list. - name: nelements_max in: query required: false schema: anyOf: - type: integer - type: 'null' description: Query for maximum value of nelements title: Nelements Max description: Query for maximum value of nelements - name: nelements_min in: query required: false schema: anyOf: - type: integer - type: 'null' description: Query for minimum value of nelements title: Nelements Min description: Query for minimum value of nelements - name: nelements in: query required: false schema: anyOf: - type: integer - type: 'null' description: Query for nelements being equal to an exact value title: Nelements description: Query for nelements being equal to an exact value - name: nelements_not_eq in: query required: false schema: anyOf: - type: integer - type: 'null' description: Query for nelements being not equal to an exact value title: Nelements Not Eq description: Query for nelements being not equal to an exact value - name: nelements_eq_any in: query required: false schema: type: string description: Query for nelements being any of these values. Provide a comma separated list. title: Nelements Eq Any description: Query for nelements being any of these values. Provide a comma separated list. - name: nelements_neq_any in: query required: false schema: type: string description: Query for nelements being not any of these values. Provide a comma separated list. title: Nelements Neq Any description: Query for nelements being not any of these values. Provide a comma separated list. - name: volume_max in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for maximum value of volume title: Volume Max description: Query for maximum value of volume - name: volume_min in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for minimum value of volume title: Volume Min description: Query for minimum value of volume - name: density_max in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for maximum value of density title: Density Max description: Query for maximum value of density - name: density_min in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for minimum value of density title: Density Min description: Query for minimum value of density - name: density_atomic_max in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for maximum value of density_atomic title: Density Atomic Max description: Query for maximum value of density_atomic - name: density_atomic_min in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for minimum value of density_atomic title: Density Atomic Min description: Query for minimum value of density_atomic - name: uncorrected_energy_per_atom_max in: query required: false schema: type: number description: Query for maximum value of uncorrected_energy_per_atom title: Uncorrected Energy Per Atom Max description: Query for maximum value of uncorrected_energy_per_atom - name: uncorrected_energy_per_atom_min in: query required: false schema: type: number description: Query for minimum value of uncorrected_energy_per_atom title: Uncorrected Energy Per Atom Min description: Query for minimum value of uncorrected_energy_per_atom - name: energy_per_atom_max in: query required: false schema: type: number description: Query for maximum value of energy_per_atom title: Energy Per Atom Max description: Query for maximum value of energy_per_atom - name: energy_per_atom_min in: query required: false schema: type: number description: Query for minimum value of energy_per_atom title: Energy Per Atom Min description: Query for minimum value of energy_per_atom - name: energy_uncertainy_per_atom_max in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for maximum value of energy_uncertainy_per_atom title: Energy Uncertainy Per Atom Max description: Query for maximum value of energy_uncertainy_per_atom - name: energy_uncertainy_per_atom_min in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for minimum value of energy_uncertainy_per_atom title: Energy Uncertainy Per Atom Min description: Query for minimum value of energy_uncertainy_per_atom - name: formation_energy_per_atom_max in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for maximum value of formation_energy_per_atom title: Formation Energy Per Atom Max description: Query for maximum value of formation_energy_per_atom - name: formation_energy_per_atom_min in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for minimum value of formation_energy_per_atom title: Formation Energy Per Atom Min description: Query for minimum value of formation_energy_per_atom - name: energy_above_hull_max in: query required: false schema: type: number description: Query for maximum value of energy_above_hull title: Energy Above Hull Max description: Query for maximum value of energy_above_hull - name: energy_above_hull_min in: query required: false schema: type: number description: Query for minimum value of energy_above_hull title: Energy Above Hull Min description: Query for minimum value of energy_above_hull - name: equilibrium_reaction_energy_per_atom_max in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for maximum value of equilibrium_reaction_energy_per_atom title: Equilibrium Reaction Energy Per Atom Max description: Query for maximum value of equilibrium_reaction_energy_per_atom - name: equilibrium_reaction_energy_per_atom_min in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for minimum value of equilibrium_reaction_energy_per_atom title: Equilibrium Reaction Energy Per Atom Min description: Query for minimum value of equilibrium_reaction_energy_per_atom - name: decomposition_enthalpy_max in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for maximum value of decomposition_enthalpy title: Decomposition Enthalpy Max description: Query for maximum value of decomposition_enthalpy - name: decomposition_enthalpy_min in: query required: false schema: anyOf: - type: number - type: 'null' description: Query for minimum value of decomposition_enthalpy title: Decomposition Enthalpy Min description: Query for minimum value of decomposition_enthalpy - name: _page in: query required: false schema: type: integer description: Page number to request (takes precedent over _limit and _skip). title: ' Page' description: Page number to request (takes precedent over _limit and _skip). - name: _per_page in: query required: false schema: type: integer description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000. default: 100 title: ' Per Page' description: Number of entries to show per page (takes precedent over _limit and _skip). Limited to 1000. - name: _skip in: query required: false schema: type: integer description: Number of entries to skip in the search. default: 0 title: ' Skip' description: Number of entries to skip in the search. - name: _limit in: query required: false schema: type: integer description: Max number of entries to return in a single query. Limited to 1000. default: 100 title: ' Limit' description: Max number of entries to return in a single query. Limited to 1000. - name: _fields in: query required: false schema: type: string description: 'Fields to project from ThermoDoc as a list of comma separated strings. Fields include: `builder_meta` `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `material_id` `deprecated` `deprecation_reasons` `last_updated` `origins` `warnings` `structure` `property_name` `thermo_type` `thermo_id` `uncorrected_energy_per_atom` `energy_per_atom` `energy_uncertainy_per_atom` `formation_energy_per_atom` `energy_above_hull` `is_stable` `equilibrium_reaction_energy_per_atom` `decomposes_to` `decomposition_enthalpy` `decomposition_enthalpy_decomposes_to` `energy_type` `entry_types` `entries`' title: ' Fields' description: 'Fields to project from ThermoDoc as a list of comma separated strings. Fields include: `builder_meta` `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `material_id` `deprecated` `deprecation_reasons` `last_updated` `origins` `warnings` `structure` `property_name` `thermo_type` `thermo_id` `uncorrected_energy_per_atom` `energy_per_atom` `energy_uncertainy_per_atom` `formation_energy_per_atom` `energy_above_hull` `is_stable` `equilibrium_reaction_energy_per_atom` `decomposes_to` `decomposition_enthalpy` `decomposition_enthalpy_decomposes_to` `energy_type` `entry_types` `entries`' - name: _all_fields in: query required: false schema: type: boolean description: Include all fields. default: false title: ' All Fields' description: Include all fields. - name: license in: query required: false schema: anyOf: - enum: - BY-C - BY-NC - All type: string - type: 'null' description: Query by license. Can be commercial or non-commercial, or both default: BY-C title: License description: Query by license. Can be commercial or non-commercial, or both responses: '200': description: Search for a ThermoDoc content: application/json: schema: $ref: '#/components/schemas/Response_ThermoDoc_' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: EmmetMeta: properties: emmet_version: anyOf: - type: string - type: 'null' title: Emmet Version description: The version of emmet this document was built with. default: 0.86.4rc4 pymatgen_version: anyOf: - type: string - type: 'null' title: Pymatgen Version description: The version of pymatgen this document was built with. default: 2026.4.16 run_id: anyOf: - type: string - type: 'null' title: Run Id description: The run id associated with this data build. batch_id: anyOf: - type: string - type: 'null' title: Batch Id description: Identifier corresponding to the origin of this document's blessed task. database_version: anyOf: - type: string - type: 'null' title: Database Version description: The database version for the built data. build_date: anyOf: - type: string format: date-time - type: 'null' title: Build Date description: The build date for this document. license: anyOf: - type: string enum: - BY-C - BY-NC - type: 'null' title: License description: License for the data entry. type: object title: EmmetMeta description: Default emmet metadata. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError Response_ThermoDoc_: properties: data: anyOf: - items: $ref: '#/components/schemas/ThermoDoc' type: array - type: 'null' title: Data description: List of returned data errors: anyOf: - items: $ref: '#/components/schemas/Error' type: array - type: 'null' title: Errors description: Any errors on processing this query meta: anyOf: - $ref: '#/components/schemas/Meta' - type: 'null' description: Extra information for the query type: object title: Response[ThermoDoc] ThermoDoc: properties: builder_meta: anyOf: - $ref: '#/components/schemas/EmmetMeta' - type: 'null' description: Builder metadata. nsites: anyOf: - type: integer - type: 'null' title: Nsites description: Total number of sites in the structure. elements: anyOf: - items: type: string type: array - type: 'null' title: Elements description: List of elements in the material. nelements: anyOf: - type: integer - type: 'null' title: Nelements description: Number of elements. composition: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Composition description: Full composition for the material. composition_reduced: anyOf: - additionalProperties: type: number type: object - type: 'null' title: Reduced Composition description: Simplified representation of the composition. formula_pretty: anyOf: - type: string - type: 'null' title: Pretty Formula description: Cleaned representation of the formula. formula_anonymous: anyOf: - type: string - type: 'null' title: Anonymous Formula description: Anonymized representation of the formula. chemsys: anyOf: - type: string - type: 'null' title: Chemical System description: Dash-separated string of elements in the material. volume: anyOf: - type: number - type: 'null' title: Volume description: Total volume for this structure in ų. density: anyOf: - type: number - type: 'null' title: Density description: Density in g/cm³. density_atomic: anyOf: - type: number - type: 'null' title: Packing Density description: The atomic packing density in ų/atom. symmetry: anyOf: - $ref: '#/components/schemas/SymmetryData' - type: 'null' description: Symmetry data for this material. material_id: anyOf: - type: string pattern: ^([A-Za-z]+-)?(\d+)(-[A-Za-z0-9]+)*$ examples: - mp-3534 - '3453' - mp-834-Ag - type: string examples: - mp-ft - task:pqrs - type: 'null' title: Material Id description: 'The Materials Project ID of the material, used as a universal reference across property documents.This comes in the form: mp-******.' deprecated: type: boolean title: Deprecated description: Whether this property document is deprecated. default: true deprecation_reasons: anyOf: - items: type: string type: array - type: 'null' title: Deprecation Reasons description: List of deprecation tags detailing why this document isn't valid. last_updated: type: string format: date-time title: Last Updated description: Timestamp for the most recent calculation update for this property. origins: anyOf: - items: $ref: '#/components/schemas/PropertyOrigin' type: array - type: 'null' title: Origins description: Dictionary for tracking the provenance of properties. warnings: items: type: string type: array title: Warnings description: Any warnings related to this property. default: [] property_name: type: string title: Property Name default: thermo thermo_type: type: string title: Thermo Type description: Functional types of calculations involved in the energy mixing scheme. thermo_id: type: string description: Unique document ID which is composed of the Material ID and thermo data type. uncorrected_energy_per_atom: type: number title: Uncorrected Energy Per Atom description: The total DFT energy of this material per atom in eV/atom. energy_per_atom: type: number title: Energy Per Atom description: The total corrected DFT energy of this material per atom in eV/atom. energy_uncertainy_per_atom: anyOf: - type: number - type: 'null' title: Energy Uncertainy Per Atom description: '' formation_energy_per_atom: anyOf: - type: number - type: 'null' title: Formation Energy Per Atom description: The formation energy per atom in eV/atom. energy_above_hull: type: number title: Energy Above Hull description: The energy above the hull in eV/Atom. is_stable: type: boolean title: Is Stable description: Flag for whether this material is on the hull and therefore stable. default: false equilibrium_reaction_energy_per_atom: anyOf: - type: number - type: 'null' title: Equilibrium Reaction Energy Per Atom description: The reaction energy of a stable entry from the neighboring equilibrium stable materials in eV. Also known as the inverse distance to hull. decomposes_to: anyOf: - items: $ref: '#/components/schemas/DecompositionProduct' type: array - type: 'null' title: Decomposes To description: List of decomposition data for this material. Only valid for metastable or unstable material. decomposition_enthalpy: anyOf: - type: number - type: 'null' title: Decomposition Enthalpy description: Decomposition enthalpy as defined by `get_decomp_and_phase_separation_energy` in pymatgen. decomposition_enthalpy_decomposes_to: anyOf: - items: $ref: '#/components/schemas/DecompositionProduct' type: array - type: 'null' title: Decomposition Enthalpy Decomposes To description: List of decomposition data associated with the decomposition_enthalpy quantity. energy_type: type: string title: Energy Type description: The type of calculation this energy evaluation comes from. entry_types: items: type: string type: array title: Entry Types description: List of available energy types computed for this material. entries: additionalProperties: additionalProperties: true type: object type: object title: Entries description: List of all entries that are valid for this material. The keys for this dictionary are names of various calculation types. type: object required: - thermo_type - thermo_id - uncorrected_energy_per_atom - energy_per_atom - energy_above_hull - energy_type - entry_types - entries title: ThermoDoc description: A thermo entry document Meta: properties: api_version: type: string title: Api Version description: A string containing the version of the Materials API implementation, e.g. v0.9.5 default: 0.86.4rc5.dev1+g77c2c1315 time_stamp: type: string format: date-time title: Time Stamp description: A string containing the date and time at which the query was executed total_doc: anyOf: - type: integer minimum: 0.0 - type: 'null' title: Total Doc description: The total number of documents available for this query facet: anyOf: - additionalProperties: true type: object - type: 'null' title: Facet description: A dictionary containing the facets available for this query additionalProperties: true type: object title: Meta description: Meta information for the MAPI Response. SymmetryData: properties: crystal_system: anyOf: - type: string - type: 'null' title: Crystal System description: The crystal system for this lattice. symbol: anyOf: - type: string - type: 'null' title: Space Group Symbol description: The spacegroup symbol for the lattice. hall: anyOf: - type: string - type: 'null' title: Hall Symbol description: Hall symbol for the lattice number: anyOf: - type: integer - type: 'null' title: Space Group Number description: The spacegroup number for the lattice. point_group: anyOf: - type: string - type: 'null' title: Point Group Symbol description: The point group for the lattice. symprec: anyOf: - type: number - type: 'null' title: Symmetry Finding Precision description: The precision provided to spglib to determine the symmetry of this structure. angle_tolerance: anyOf: - type: number - type: 'null' title: Angle Tolerance description: Angle tolerance provided to spglib to determine the symmetry of this structure. version: anyOf: - type: string - type: 'null' title: spglib version type: object title: SymmetryData description: Defines a symmetry data set for materials documents DecompositionProduct: properties: material_id: anyOf: - type: string pattern: ^([A-Za-z]+-)?(\d+)(-[A-Za-z0-9]+)*$ examples: - mp-3534 - '3453' - mp-834-Ag - type: string examples: - mp-ft - task:pqrs - type: 'null' title: Material Id description: The Materials Project ID for the material this decomposition points to. formula: anyOf: - type: string - type: 'null' title: Formula description: The formula of the decomposed material this material decomposes to. amount: anyOf: - type: number - type: 'null' title: Amount description: The amount of the decomposed material by formula units this this material decomposes to. type: object title: DecompositionProduct description: Entry metadata for a decomposition process Error: properties: code: type: integer title: Code description: The error code message: type: string title: Message description: The description of the error type: object required: - code - message title: Error description: Base Error model for General API. PropertyOrigin: properties: name: type: string title: Name description: The property name task_id: anyOf: - type: string pattern: ^([A-Za-z]+-)?(\d+)(-[A-Za-z0-9]+)*$ examples: - mp-3534 - '3453' - mp-834-Ag - type: string examples: - mp-ft - task:pqrs title: Task Id description: The calculation ID this property comes from. last_updated: type: string format: date-time title: Last Updated description: The timestamp when this calculation was last updated type: object required: - name - task_id title: PropertyOrigin description: Provenance document for the origin of properties in a material document HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError securitySchemes: ApiKeyAuth: descriptions: MP API key to authorize requests name: X-API-KEY in: header type: apiKey