API Reference¶

This is just a brief summary of all API endpoints of the NOMAD API. For a more compelling documention consult our swagger dashboards:

(NOMAD API)[swagger dashboard](https://nomad-lab.eu/prod/rae/api/)
(NOMAD’s Optimade API)[swagger dashboard](https://nomad-lab.eu/prod/rae/optimade/)

Summary¶

Resource	Operation	Description
	GET /api/encyclopedia/suggestions
	POST /api/encyclopedia/materials/
	GET /api/archive/download
	GET /api/uploads/command
	POST /api/archive/query
	GET /api/mirror/users
	GET /api/repo/quantities
	PUT /api/auth/users
	GET /api/auth/users
	POST /api/repo/edit
	GET /api/raw/query
	POST /api/raw/query
	GET /dcat/swagger.json
	GET /dcat/catalog/
	GET /api/swagger.json
	PUT /api/datasets/
	GET /api/datasets/
	GET /api/metainfo/
	GET /api/uploads/
	GET /api/info/
	GET /api/auth/
	GET /api/repo/
	POST /api/repo/
	GET /alive
	GET /dcat/
	GET /api/
	POST /api/encyclopedia/materials/(string:material_id)/calculations/(string:calc_id)
	GET /api/encyclopedia/materials/(string:material_id)/calculations
	POST /api/encyclopedia/materials/(string:material_id)/statistics
	POST /api/encyclopedia/materials/(string:material_id)/reports
	GET /api/encyclopedia/materials/(string:material_id)/groups/(string:group_type)/(string:group_id)
	GET /api/encyclopedia/materials/(string:material_id)/groups
	GET /api/encyclopedia/materials/(string:material_id)
	GET /api/archive/logs/(string:upload_id)/(string:calc_id)
	GET /api/mirror/files/(string:upload_id)
	GET /api/repo/suggestions/(string:quantity)
	GET /api/repo/quantity/(string:quantity)
	GET /api/raw/calc/(string:upload_id)/(string:calc_id)/(path:path)
	GET /api/raw/calc/(string:upload_id)/(string:calc_id)/
	GET /dcat/datasets/(string:entry_id)
	GET /api/metainfo/(string:metainfo_package_name)
	GET /api/datasets/(path:name)
	DELETE /api/datasets/(path:name)
	POST /api/datasets/(path:name)
	GET /api/archive/(string:upload_id)/(string:calc_id)
	GET /api/uploads/(string:upload_id)
	DELETE /api/uploads/(string:upload_id)
	POST /api/uploads/(string:upload_id)
	GET /api/mirror/(string:upload_id)
	GET /api/repo/(string:upload_id)/(string:calc_id)
	GET /api/raw/(string:upload_id)/(path:path)
	GET /api/raw/(string:upload_id)
	POST /api/raw/(string:upload_id)
	GET /encyclopedia/(path:filename)
	GET /swaggerui/(path:filename)
	GET /docs/(path:filename)
	GET /dist/(path:filename)
	GET /gui/(path:filename)

API(s) Details¶

GET /api/encyclopedia/suggestions¶: Dynamically retrieves a list of unique values for the given property.

POST /api/encyclopedia/materials/¶: Search materials based on their properties.

GET /api/archive/download¶

Get calculation data in archive form from all query results.

See /repo endpoint for documentation on the search parameters.

Zip files are streamed; instead of 401 errors, the zip file will just not contain any files that the user is not authorized to access.

The zip file will contain a manifest.json with the repository meta data.

GET /api/uploads/command¶: Get url and example command for shell based uploads.

POST /api/archive/query¶

Post a query schema and return it filled with archive data.

See /repo endpoint for documentation on the search parameters.

This endpoint uses pagination (see /repo) or id aggregation to handle large result sets over multiple requests. Use aggregation.after and aggregation.per_page to request a certain page with id aggregation.

The actual data are in results and a supplementary python code (curl) to execute search is in python (curl).

GET /api/mirror/users¶: Download user list for mirrors

GET /api/repo/quantities¶

Retrieve quantity values for multiple quantities at once.

You can use the various quantities to search/filter for. For some of the indexed quantities this endpoint returns aggregation information. This means you will be given a list of all possible values and the number of entries that have the certain value. You can also use these aggregations on an empty search to determine the possible values.

There is no ordering and no pagination and not after key based scrolling. Instead there is an ‘after’ key based scrolling.

The result will contain a ‘quantities’ key with a dict of quantity names and the retrieved values as values.

PUT /api/auth/users¶: Invite a new user.

GET /api/auth/users¶: Get existing users.

POST /api/repo/edit¶: Edit repository metadata.

GET /api/raw/query¶

Download a .zip file with all raw-files for all entries that match the given search parameters.

See /repo endpoint for documentation on the search parameters.

Zip files are streamed; instead of 401 errors, the zip file will just not contain any files that the user is not authorized to access.

The zip file will contain a manifest.json with the repository meta data.

POST /api/raw/query¶

Download a .zip file with all raw-files for all entries that match the given search parameters.

See /repo endpoint for documentation on the search parameters.

Zip files are streamed; instead of 401 errors, the zip file will just not contain any files that the user is not authorized to access.

The zip file will contain a manifest.json with the repository meta data.

GET /dcat/swagger.json¶: Render the Swagger specifications as JSON

GET /dcat/catalog/¶: Returns a page of DCAT datasets.

GET /api/swagger.json¶: Render the Swagger specifications as JSON

PUT /api/datasets/¶: Creates a new dataset.

GET /api/datasets/¶: Retrieve a list of all datasets of the authenticated user.

GET /api/metainfo/¶: Returns all metainfo packages.

GET /api/uploads/¶: Get the list of all uploads from the authenticated user.

GET /api/info/¶: Return information about the nomad backend and its configuration.

GET /api/auth/¶

Provides authentication information. This endpoint requires authentification. Like all endpoints the OIDC access token based authentification. In additional, basic HTTP authentification can be used. This allows to login and acquire an access token.

The response contains a short (10s) term JWT token that can be used to sign URLs with a signature_token query parameter, e.g. for file downloads on the raw or archive api endpoints; a short upload_token that is used in curl command line based uploads; and the OIDC JWT access token.

GET /api/repo/¶

Search for calculations in the repository form, paginated.

The owner parameter determines the overall entries to search through. Possible values are: all (show all entries visible to the current user), public (show all publically visible entries), user (show all user entries, requires login), staging (show all user entries in staging area, requires login).

You can use the various quantities to search/filter for. For some of the indexed quantities this endpoint returns aggregation information. This means you will be given a list of all possible values and the number of entries that have the certain value. You can also use these aggregations on an empty search to determine the possible values.

The pagination parameters allows determine which page to return via the page and per_page parameters. Pagination however, is limited to the first 100k (depending on ES configuration) hits.

An alternative to pagination is to use scroll and scroll_id. With scroll you will get a scroll_id on the first request. Each call with scroll and the respective scroll_id will return the next per_page (here the default is 1000) results. Scroll however, ignores ordering and does not return aggregations. The scroll view used in the background will stay alive for 1 minute between requests. If the given scroll_id is not available anymore, a HTTP 400 is raised.

The search will return aggregations on a predefined set of quantities. Aggregations will tell you what quantity values exist and how many entries match those values.

Ordering is determined by order_by and order parameters. Default is upload_time in decending order.

POST /api/repo/¶

Search for calculations in the repository form, paginated.

The owner parameter determines the overall entries to search through. Possible values are: all (show all entries visible to the current user), public (show all publically visible entries), user (show all user entries, requires login), staging (show all user entries in staging area, requires login).

You can use the various quantities to search/filter for. For some of the indexed quantities this endpoint returns aggregation information. This means you will be given a list of all possible values and the number of entries that have the certain value. You can also use these aggregations on an empty search to determine the possible values.

The pagination parameters allows determine which page to return via the page and per_page parameters. Pagination however, is limited to the first 100k (depending on ES configuration) hits.

An alternative to pagination is to use scroll and scroll_id. With scroll you will get a scroll_id on the first request. Each call with scroll and the respective scroll_id will return the next per_page (here the default is 1000) results. Scroll however, ignores ordering and does not return aggregations. The scroll view used in the background will stay alive for 1 minute between requests. If the given scroll_id is not available anymore, a HTTP 400 is raised.

The search will return aggregations on a predefined set of quantities. Aggregations will tell you what quantity values exist and how many entries match those values.

Ordering is determined by order_by and order parameters. Default is upload_time in decending order.

GET /alive¶: Simple endpoint to utilize kubernetes liveness/readiness probing.

GET /dcat/¶: Override this method to customize the documentation page

GET /api/¶: Override this method to customize the documentation page

POST /api/encyclopedia/materials/(string: material_id)/calculations/(string: calc_id)¶: Get properties from a specific calculation related to a material.

GET /api/encyclopedia/materials/(string: material_id)/calculations¶

Used to return information about all calculations related to the given material.

Returns a list of all calculations and a representative calculation for few select quantities that are shown in the material overview page.

POST /api/encyclopedia/materials/(string: material_id)/statistics¶: Used to return statistics related to the specified material and calculations.

POST /api/encyclopedia/materials/(string: material_id)/reports¶: Post an error report on a material. Requires authentication.

GET /api/encyclopedia/materials/(string: material_id)/groups/(string: group_type)/(string: group_id)¶: Used to query detailed information about a specific calculation group.

GET /api/encyclopedia/materials/(string: material_id)/groups¶

Returns a summary of the calculation groups that were identified for this material.

Two types of groups are reported: equation of state groups and parameter variation groups. Equation of state groups contain calculations with identical method and material, but different volume. Parameter variation groups contain identical structure but different methods. The response contains dictionaries for both groups (‘groups_eos’ and ‘groups_par’). These dictionaries map a group id with a list of calculation ids.

GET /api/encyclopedia/materials/(string: material_id)¶: Used to retrieve basic information related to a material.

GET /api/archive/logs/(string: upload_id)/(string: calc_id)¶

Get calculation processing log.

Calcs are references via upload_id, calc_id pairs.

GET /api/mirror/files/(string: upload_id)¶: Download archive and raw files for mirrors

GET /api/repo/suggestions/(string: quantity)¶

Retrieve the top values for the given quantity from entries matching the search. Values can be filtered by to include a given value.

There is no ordering, no pagination, and no scroll interface.

The result will contain a ‘suggestions’ key with values. There will be upto ‘size’ many values.

GET /api/repo/quantity/(string: quantity)¶

Retrieve quantity values from entries matching the search.

You can use the various quantities to search/filter for. For some of the indexed quantities this endpoint returns aggregation information. This means you will be given a list of all possible values and the number of entries that have the certain value. You can also use these aggregations on an empty search to determine the possible values.

There is no ordering and no pagination. Instead there is an ‘after’ key based scrolling. The result will contain an ‘after’ value, that can be specified for the next request. You can use the ‘size’ and ‘after’ parameters accordingly.

The result will contain a ‘quantity’ key with quantity values and the “after” value. There will be upto ‘size’ many values. For the rest of the values use the “after” parameter in another request.

GET /api/raw/calc/(string: upload_id)/(string: calc_id)/(path: path)¶

Get a single raw calculation file, calculation contents, or all files for a given calculation.

The ‘upload_id’ parameter needs to identify an existing upload. The ‘calc_id’ parameter needs to identify a calculation within in the upload.

This endpoint behaves exactly like /raw/<upload_id>/<path>, but the path is now relative to the calculation and not the upload.

GET /api/raw/calc/(string: upload_id)/(string: calc_id)/¶

Get calculation contents.

This is basically /raw/calc/<upload_id>/<calc_id>/<path> with an empty path, since having an empty path parameter is not possible.

GET /dcat/datasets/(string: entry_id)¶: Returns a DCAT dataset for a given NOMAD entry id.

GET /api/metainfo/(string: metainfo_package_name)¶: Get a JSON representation of a NOMAD Metainfo package. The package name is the qualified Python name of the respective module that contains the definitions. Examples are nomad.datamodel.metainfo.common_dft or vaspparser.metainfo. If the desired package depends on other packages, these will also be contain in the results.

GET /api/datasets/(path: name)¶: Retrieve a dataset by name.

DELETE /api/datasets/(path: name)¶: Delete the dataset.

POST /api/datasets/(path: name)¶: Assign a DOI to the dataset.

GET /api/archive/(string: upload_id)/(string: calc_id)¶

Get calculation data in archive form.

Calcs are references via upload_id, calc_id pairs.

GET /api/uploads/(string: upload_id)¶

Get an update for an existing upload.

Will not only return the upload, but also its calculations paginated. Use the pagination params to determine the page.

DELETE /api/uploads/(string: upload_id)¶

Delete an existing upload.

Only uploads that are sill in staging, not already deleted, not still uploaded, and not currently processed, can be deleted.

POST /api/uploads/(string: upload_id)¶

Execute an upload operation. Available operations are publish, re-process, publish-to-central-nomad.

Publish accepts further meta data that allows to provide coauthors, comments, external references, etc. See the model for details. The fields that start with _underscore are only available for users with administrative privileges.

Publish changes the visibility of the upload. Clients can specify the visibility via meta data.

Re-process will re-process the upload and produce updated repository metadata and archive. Only published uploads that are not processing at the moment are allowed. Only for uploads where calculations have been processed with an older nomad version.

Publish-to-central-nomad will upload the upload to the central NOMAD. This is only available on an OASIS. The upload must already be published on the OASIS.

GET /api/mirror/(string: upload_id)¶: Export upload (and all calc) metadata for mirrors.

GET /api/repo/(string: upload_id)/(string: calc_id)¶

Get calculation metadata in repository form.

Repository metadata only entails the quantities shown in the repository. Calcs are references via upload_id, calc_id pairs.

GET /api/raw/(string: upload_id)/(path: path)¶

Get a single raw calculation file, directory contents, or whole directory sub-tree from a given upload.

The ‘upload_id’ parameter needs to identify an existing upload.

If the upload is not yet published or contains requested data with embargo, proper authentication is required. This can be done via HTTP headers as usual. But, if you need to access files via plain URLs (e.g. for curl, download link, etc.), URLs for this endpoint can be token signed (see also /auth/token). For unpublished uploads, authentication is required regardless. For (partially) embargoed data, multi file downloads work, but will not contain any embargoed data.

If the given path points to a file, the file is provided with the appropriate Content-Type header. A 401 is returned for staging, embargo files with unsigned or wrongly signed URLs. When accessing a file, the additional query parameters ‘length’ and ‘offset’ can be used to partially download a file’s content.

If the given path points to a directory, the content (names, sizes, type) is returned as a json body. Only visible items (depending on authenticated user, token) are returned.

If the given path ends with the ‘*’ wildcard character, all upload contents that match the given path at the start, will be returned as a .zip file body. Zip files are streamed; instead of 401 errors, the zip file will just not contain any files that the user is not authorized to access.

GET /api/raw/(string: upload_id)¶: Download multiple raw calculation files. Download multiple raw calculation files in a .zip file. Zip files are streamed; instead of 401 errors, the zip file will just not contain any files that the user is not authorized to access.

POST /api/raw/(string: upload_id)¶

Download multiple raw calculation files in a .zip file.

Zip files are streamed; instead of 401 errors, the zip file will just not contain any files that the user is not authorized to access.

GET /encyclopedia/(path: filename)¶: Function used internally to send static files from the static folder to the browser.

New in version 0.5.

GET /swaggerui/(path: filename)¶: Function used internally to send static files from the static folder to the browser.

New in version 0.5.

GET /docs/(path: filename)¶: Function used internally to send static files from the static folder to the browser.

New in version 0.5.

GET /dist/(path: filename)¶: Function used internally to send static files from the static folder to the browser.

New in version 0.5.

GET /gui/(path: filename)¶: Function used internally to send static files from the static folder to the browser.

New in version 0.5.