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:

Summary

Resource

Operation

Description

GET /optimade/index/v1/links

GET /optimade/index/v1/info

GET /optimade/v1/info/calculations

GET /optimade/v1/info/structures

GET /optimade/v1/calculations

GET /optimade/v1/structures

GET /optimade/v1/links

GET /optimade/v1/info

POST /api/encyclopedia/materials

GET /api/archive/download

GET /api/uploads/command

POST /api/archive/query

GET /api/mirror/users

GET /api/repo/quantities

GET /api/auth/users

PUT /api/auth/users

POST /api/repo/edit

POST /api/raw/query

GET /api/raw/query

GET /optimade/swagger.json

GET /api/swagger.json

GET /api/datasets/

PUT /api/datasets/

GET /api/metainfo/

GET /api/uploads/

GET /api/info/

GET /api/auth/

POST /api/repo/

GET /api/repo/

GET /optimade/

GET /alive

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

GET /api/encyclopedia/materials/(string:material_id)/groups/(string:group_type)/(string:group_id)

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

GET /optimade/v1/calculations/(string:id)

GET /optimade/v1/structures/(string:id)

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

GET /api/metainfo/legacy/(string:metainfo_package_name)

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 /api/metainfo/(string:metainfo_package_name)

DELETE /api/datasets/(path:name)

POST /api/datasets/(path:name)

GET /api/datasets/(path:name)

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

DELETE /api/uploads/(string:upload_id)

POST /api/uploads/(string:upload_id)

GET /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)

POST /api/raw/(string:upload_id)

GET /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

Returns information relating to the API implementation-

GET /optimade/index/v1/info

Returns information relating to the API implementation-

GET /optimade/v1/info/calculations

Returns information about the calculation endpoint implementation

GET /optimade/v1/info/structures

Returns information about the structures endpoint implementation

GET /optimade/v1/calculations

Returns a list of calculations that match the given optimade filter expression.

GET /optimade/v1/structures

Returns a list of structures that match the given optimade filter expression.

Returns information about related optimade databases

GET /optimade/v1/info

Returns information about this optimade implementation

POST /api/encyclopedia/materials

Used to query a list of materials with the given search options.

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.

GET /api/auth/users

Get existing users.

PUT /api/auth/users

Invite a new user.

POST /api/repo/edit

Edit repository metadata.

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 /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 /optimade/swagger.json

Render the Swagger specifications as JSON

GET /api/swagger.json

Render the Swagger specifications as JSON

GET /api/datasets/

Retrieve a list of all datasets of the authenticated user.

PUT /api/datasets/

Creates a new dataset.

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.

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 /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 /optimade/

Override this method to customize the documentation page

GET /alive

Simple endpoint to utilize kubernetes liveness/readiness probing.

GET /api/

Override this method to customize the documentation page

POST /api/encyclopedia/materials/(string: material_id)/calculations/(string: calc_id)

Used to return calculation details. Some properties are not available in the ES index and are instead read from the Archive directly.

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

Used to return all calculations related to the given material. Also returns a representative calculation for each property shown in the overview page.

POST /api/encyclopedia/materials/(string: material_id)/statistics

Used to return statistics related to the specified material and calculations.

GET /api/encyclopedia/materials/(string: material_id)/groups/(string: group_type)/(string: group_id)

Used to query detailed information for 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.

GET /optimade/v1/calculations/(string: id)

Retrieve a single calculation for the given id

GET /optimade/v1/structures/(string: id)

Retrieve a single structure for the given id

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

Used to retrieve basic information related to the specified material.

GET /api/metainfo/legacy/(string: metainfo_package_name)

Get a JSON representation of the NOMAD Metainfo in its old legacy JSON format.

You can get the metainfo for ‘common’, and parser/code metainfo packages. Parser/code packages constain the necessary definitions that the respective parser/code might use. ‘Common’ contains all non specific general definitions. Other required packages might also be returned, e.g. a parser might organize its definitions in multiple packages.

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 /api/metainfo/(string: metainfo_package_name)

Get a JSON representation of the NOMAD Metainfo.

You can get the metainfo for ‘common’, and parser/code metainfo packages. Parser/code packages constain the necessary definitions that the respective parser/code might use. ‘Common’ contains all non specific general definitions. Other required packages might also be returned, e.g. a parser might organize its definitions in multiple packages.

DELETE /api/datasets/(path: name)

Delete the dataset.

POST /api/datasets/(path: name)

Assign a DOI to the dataset.

GET /api/datasets/(path: name)

Retrieve a dataset by name.

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

Get calculation data in archive form.

Calcs are references via upload_id, calc_id pairs.

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 and re-process

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.

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.

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.

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 /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.

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.