openapi: 3.1.0
info:
title: Materials Project Defect Tasks Materials Tasks 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 <heavy.api.use@materialsproject.org>. 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 <https://next-gen.materialsproject.org/api>.\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 Tasks
description: Route for "core" information associated with a given calculation in the Materials Project database. Multiple calculations can ultimately be associated with a unique material, and are the source of its reported properties. The unique identifier for a calculation is its `task_id`. Note that the `material_id` chosen for a given material is sourced from one of the `task_id` values associated with it. Core data in this context refers to calculation quantities such as parsed input and output data (e.g. VASP input flags, atomic forces, structures) and runtime statistics. See the `TaskDoc` schema for a full list of fields returned by this route.
paths:
/materials/tasks/trajectory/:
get:
tags:
- Materials Tasks
summary: Get TrajectoryDoc documents
operationId: search_materials_tasks_trajectory__get
parameters:
- name: task_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of task_ids to query on
title: Task Ids
description: Comma-separated list of task_ids to query on
- 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.
responses:
'200':
description: Search for a TrajectoryDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_TrajectoryDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/materials/tasks/entries/:
get:
tags:
- Materials Tasks
summary: Get EntryDoc documents
operationId: search_materials_tasks_entries__get
parameters:
- name: task_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of task_ids to query on
title: Task Ids
description: Comma-separated list of task_ids to query on
- 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.
responses:
'200':
description: Search for a EntryDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_EntryDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/materials/tasks/deprecation/:
get:
tags:
- Materials Tasks
summary: Get DeprecationDoc documents
operationId: search_materials_tasks_deprecation__get
parameters:
- name: task_ids
in: query
required: true
schema:
type: string
description: Comma-separated list of task_ids to query on
title: Task Ids
description: Comma-separated list of task_ids to query on
- 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.
responses:
'200':
description: Search for a DeprecationDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_DeprecationDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/materials/tasks/:
get:
tags:
- Materials Tasks
summary: Get TaskDoc documents
operationId: search_materials_tasks__get
parameters:
- name: batch_id
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Query by batch identifier
title: Batch Id
description: Query by batch identifier
- name: batch_id_not_eq
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Exclude batch identifier
title: Batch Id Not Eq
description: Exclude batch identifier
- name: batch_id_eq_any
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Query by a comma-separated list of batch identifiers
title: Batch Id Eq Any
description: Query by a comma-separated list of batch identifiers
- name: batch_id_neq_any
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Exclude a comma-separated list of batch identifiers
title: Batch Id Neq Any
description: Exclude a comma-separated list of batch identifiers
- 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: elements
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Query by elements in the material composition as a comma-separated list
title: Elements
description: Query by elements in the material composition as a comma-separated list
- name: exclude_elements
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Query by excluded elements in the material composition as a comma-separated list
title: Exclude Elements
description: Query by excluded elements in the material composition as a comma-separated list
- name: task_ids
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Comma-separated list of task_ids to query on
title: Task Ids
description: Comma-separated list of task_ids to query on
- name: last_updated_min
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Minimum last updated UTC datetime
title: Last Updated Min
description: Minimum last updated UTC datetime
- name: last_updated_max
in: query
required: false
schema:
anyOf:
- type: string
format: date-time
- type: 'null'
description: Maximum last updated UTC datetime
title: Last Updated Max
description: Maximum last updated UTC datetime
- name: _forward
in: query
required: false
schema:
type: boolean
description: Whether to page forward (True) or backward (False) in the search results.
default: true
title: ' Forward'
description: Whether to page forward (True) or backward (False) in the search results.
- name: _pagination_token
in: query
required: false
schema:
type: string
description: Pagination token for the next set of results.
title: ' Pagination Token'
description: Pagination token for the next set of results.
- 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 TaskDoc as a list of comma separated strings. Fields include: `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `batch_id` `calc_type` `completed_at` `dir_name` `icsd_id` `input` `last_updated` `orig_inputs` `output` `run_type` `structure` `tags` `task_id` `task_type` `transformations` `vasp_objects` `vasp_version` `additional_json` `analysis` `author` `calcs_reversed` `custodian` `entry` `included_objects` `run_stats` `state` `task_label`'
title: ' Fields'
description: 'Fields to project from TaskDoc as a list of comma separated strings. Fields include: `nsites` `elements` `nelements` `composition` `composition_reduced` `formula_pretty` `formula_anonymous` `chemsys` `volume` `density` `density_atomic` `symmetry` `batch_id` `calc_type` `completed_at` `dir_name` `icsd_id` `input` `last_updated` `orig_inputs` `output` `run_type` `structure` `tags` `task_id` `task_type` `transformations` `vasp_objects` `vasp_version` `additional_json` `analysis` `author` `calcs_reversed` `custodian` `entry` `included_objects` `run_stats` `state` `task_label`'
- name: _all_fields
in: query
required: false
schema:
type: boolean
description: Include all fields.
default: false
title: ' All Fields'
description: Include all fields.
responses:
'200':
description: Search for a TaskDoc
content:
application/json:
schema:
$ref: '#/components/schemas/Response_TaskDoc_'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
TypedPerIonProps:
properties:
s:
type: number
title: S
p:
type: number
title: P
d:
type: number
title: D
tot:
type: number
title: Tot
type: object
required:
- s
- p
- d
- tot
title: TypedPerIonProps
TypedPotcarStatsDict:
properties:
header:
$ref: '#/components/schemas/TypedStatisticsDict'
data:
$ref: '#/components/schemas/TypedStatisticsDict'
type: object
required:
- header
- data
title: TypedPotcarStatsDict
TypedAggregateProperitesDict:
properties:
magmom:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Magmom
charge:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Charge
velocities:
anyOf:
- items:
prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
title: Velocities
selective_dynamics:
anyOf:
- items:
prefixItems:
- type: boolean
- type: boolean
- type: boolean
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
title: Selective Dynamics
type: object
title: TypedAggregateProperitesDict
CustodianDoc:
properties:
corrections:
anyOf:
- items: {}
type: array
- type: 'null'
title: Custodian Corrections
description: List of custodian correction data for calculation.
job:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Custodian Job Data
description: Job data logged by custodian.
type: object
title: CustodianDoc
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.
RelaxTrajectory:
properties:
elements:
items:
type: integer
type: array
title: Elements
description: The proton number Z of the elements in the sites
cart_coords:
items:
anyOf:
- items:
prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
type: array
title: Cart Coords
description: The Cartesian coordinates (Å) of the sites at each ionic step
num_ionic_steps:
type: integer
title: Num Ionic Steps
description: The number of ionic steps.
lattice:
anyOf:
- items:
prefixItems:
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
title: Lattice
description: If a list containing only one 3x3 matrix, it is assumed that the lattice was held constant through the simulation. If a list of (multiple) 3x3 matrices, this should be the lattice at each ionic step in the calculation. If None, a non-periodic system is assumed.
energy:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Energy
description: The total energy at each ionic step.
forces:
anyOf:
- items:
items:
prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
type: array
- type: 'null'
title: Forces
description: The interatomic forces.
stress:
anyOf:
- items:
prefixItems:
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
- prefixItems:
- type: number
- type: number
- type: number
type: array
maxItems: 3
minItems: 3
type: array
maxItems: 3
minItems: 3
type: array
- type: 'null'
title: Stress
description: The 3x3 stress tensor.
electronic_steps:
anyOf:
- items:
items:
$ref: '#/components/schemas/ElectronicStep'
type: array
type: array
- type: 'null'
title: Electronic Steps
description: The electronic steps within a given ionic step.
num_electronic_steps:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Num Electronic Steps
description: The number of electronic steps within each ionic step.
e_wo_entrp:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: E Wo Entrp
description: The total energy in eV without electronic pseudoentropy from smearing of the Fermi surface.
e_fr_energy:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: E Fr Energy
description: The total electronic free energy in eV.
identifier:
anyOf:
- type: string
- type: 'null'
title: Identifier
description: Identifier of this trajectory, e.g., task ID.
task_type:
anyOf:
- type: string
- type: 'null'
title: Task Type
description: The TaskType of the calculation used to generate this trajectory.
run_type:
anyOf:
- type: string
- type: 'null'
title: Run Type
description: The RunType of the calculation used to generate this trajectory.
type: object
required:
- elements
- cart_coords
- num_ionic_steps
title: RelaxTrajectory
description: 'Low memory schema for relaxation trajectories that can interface with parquet, pymatgen, and ASE.
This schema is intended primarily for VASP relaxation trajectories, but could be adapted to
generic electronic structure trajectories.
Note that for VASP calculations, energies are in eV, forces in eV/Å, and stress tensors in kilobar.'
TypedSpeciesDict:
properties:
element:
anyOf:
- type: string
- type: 'null'
title: Element
oxidation_state:
anyOf:
- type: number
- type: 'null'
title: Oxidation State
spin:
anyOf:
- type: number
- type: 'null'
title: Spin
occu:
anyOf:
- type: number
- type: 'null'
title: Occu
type: object
title: TypedSpeciesDict
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
PotcarSpec:
properties:
titel:
anyOf:
- type: string
- type: 'null'
title: Titel
description: TITEL field from POTCAR header
hash:
anyOf:
- type: string
- type: 'null'
title: Hash
description: md5 hash of POTCAR file
summary_stats:
anyOf:
- $ref: '#/components/schemas/TypedPotcarSummaryStatsDict'
- type: 'null'
description: summary statistics used to ID POTCARs without hashing
type: object
title: PotcarSpec
description: Document defining a VASP POTCAR specification.
TypedSiteDict:
properties:
label:
anyOf:
- type: string
- type: 'null'
title: Label
name:
anyOf:
- type: string
- type: 'null'
title: Name
properties:
anyOf:
- $ref: '#/components/schemas/TypedSiteProperitesDict'
- type: 'null'
species:
anyOf:
- items:
$ref: '#/components/schemas/TypedSpeciesDict'
type: array
- type: 'null'
title: Species
abc:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Abc
xyz:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Xyz
type: object
title: TypedSiteDict
BaderAnalysis:
properties:
min_dist:
items:
type: number
type: array
title: Min Dist
charge:
items:
type: number
type: array
title: Charge
atomic_volume:
items:
type: number
type: array
title: Atomic Volume
vacuum_charge:
type: number
title: Vacuum Charge
vacuum_volume:
type: number
title: Vacuum Volume
reference_used:
type: boolean
title: Reference Used
bader_version:
type: number
title: Bader Version
charge_transfer:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Charge Transfer
magmom:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Magmom
type: object
required:
- min_dist
- charge
- atomic_volume
- vacuum_charge
- vacuum_volume
- reference_used
- bader_version
title: BaderAnalysis
description: 'Output of pymatgen.command_line.bader_caller.bader_analysis_from_objects
We omit the `charge_densities` field, since these are too large
to justify storing in the document model.
Charge densities can already be stored in TaskDoc.vasp_objects'
FrequencyDependentDielectric:
properties:
real:
anyOf:
- items:
items:
type: number
type: array
type: array
- type: 'null'
title: Real
description: Real part of the frequency dependent dielectric constant, given at each energy as 6 components according to XX, YY, ZZ, XY, YZ, ZX
imaginary:
anyOf:
- items:
items:
type: number
type: array
type: array
- type: 'null'
title: Imaginary
description: Imaginary part of the frequency dependent dielectric constant, given at each energy as 6 components according to XX, YY, ZZ, XY, YZ, ZX
energy:
anyOf:
- items:
type: number
type: array
- type: 'null'
title: Energy
description: Energies at which the real and imaginary parts of the dielectricconstant are given
type: object
title: FrequencyDependentDielectric
description: Frequency-dependent dielectric data.
TaskDoc:
properties:
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: Den
# --- truncated at 32 KB (82 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/materials-project/refs/heads/main/openapi/materials-project-materials-tasks-api-openapi.yml