{

"openapi": "3.0.2",

"info": {

"title": "OPTIMADE API",

"description": "The [Open Databases Integration for Materials Design (OPTIMADE) consortium](https://www.optimade.org/) aims to make materials databases interoperational by developing a common REST API.\n\nThis specification is generated using [`optimade-python-tools`](https://github.com/Materials-Consortia/optimade-python-tools/tree/v0.8.1) v0.8.1.",

"version": "0.10.1"

},

"paths": {

"/v0/info": {

"get": {

"tags": [

"Info"

],

"summary": "Get Info",

"operationId": "get_info_v0_info_get",

"responses": {

"200": {

"description": "Successful Response",

"content": {

"application/json": {

"schema": {

"title": "Response Get Info V0 Info Get",

"anyOf": [

{

"$ref": "#/components/schemas/InfoResponse"

},

{

"$ref": "#/components/schemas/ErrorResponse"

}

]

}

}

}

}

}

}

},

"/v0/info/{entry}": {

"get": {

"tags": [

"Info"

],

"summary": "Get Entry Info",

"operationId": "get_entry_info_v0_info__entry__get",

"parameters": [

{

"required": true,

"schema": {

"title": "Entry",

"type": "string"

},

"name": "entry",

"in": "path"

}

],

"responses": {

"200": {

"description": "Successful Response",

"content": {

"application/json": {

"schema": {

"title": "Response Get Entry Info V0 Info Entry Get",

"anyOf": [

{

"$ref": "#/components/schemas/EntryInfoResponse"

},

{

"$ref": "#/components/schemas/ErrorResponse"

}

]

}

}

}

},

"422": {

"description": "Validation Error",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/HTTPValidationError"

}

}

}

}

}

}

},

"/v0/links": {

"get": {

"tags": [

"Links"

],

"summary": "Get Links",

"operationId": "get_links_v0_links_get",

"parameters": [

{

"description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).",

"required": false,

"schema": {

"title": "Filter",

"type": "string",

"description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).",

"default": ""

},

"name": "filter",

"in": "query"

},

{

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"required": false,

"schema": {

"title": "Response Format",

"type": "string",

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"default": "json"

},

"name": "response_format",

"in": "query"

},

{

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"required": false,

"schema": {

"title": "Email Address",

"type": "string",

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"format": "email",

"default": ""

},

"name": "email_address",

"in": "query"

},

{

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"required": false,

"schema": {

"title": "Response Fields",

"pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",

"type": "string",

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"default": ""

},

"name": "response_fields",

"in": "query"

},

{

"description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name. The set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).",

"required": false,

"schema": {

"title": "Sort",

"pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",

"type": "string",

"description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name. The set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).",

"default": ""

},

"name": "sort",

"in": "query"

},

{

"description": "Sets a numerical limit on the number of entries returned. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.",

"required": false,

"schema": {

"title": "Page Limit",

"minimum": 0.0,

"type": "integer",

"description": "Sets a numerical limit on the number of entries returned. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.",

"default": 20

},

"name": "page_limit",

"in": "query"

},

{

"description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",

"required": false,

"schema": {

"title": "Page Offset",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",

"default": 0

},

"name": "page_offset",

"in": "query"

},

{

"description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",

"required": false,

"schema": {

"title": "Page Number",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",

"default": 0

},

"name": "page_number",

"in": "query"

},

{

"description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",

"required": false,

"schema": {

"title": "Page Cursor",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",

"default": 0

},

"name": "page_cursor",

"in": "query"

},

{

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",

"required": false,

"schema": {

"title": "Page Above",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",

"default": 0

},

"name": "page_above",

"in": "query"

},

{

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",

"required": false,

"schema": {

"title": "Page Below",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",

"default": 0

},

"name": "page_below",

"in": "query"

},

{

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"required": false,

"schema": {

"title": "Include",

"type": "string",

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"default": "references"

},

"name": "include",

"in": "query"

}

],

"responses": {

"200": {

"description": "Successful Response",

"content": {

"application/json": {

"schema": {

"title": "Response Get Links V0 Links Get",

"anyOf": [

{

"$ref": "#/components/schemas/LinksResponse"

},

{

"$ref": "#/components/schemas/ErrorResponse"

}

]

}

}

}

},

"422": {

"description": "Validation Error",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/HTTPValidationError"

}

}

}

}

}

}

},

"/v0/references": {

"get": {

"tags": [

"References"

],

"summary": "Get References",

"operationId": "get_references_v0_references_get",

"parameters": [

{

"description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).",

"required": false,

"schema": {

"title": "Filter",

"type": "string",

"description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).",

"default": ""

},

"name": "filter",

"in": "query"

},

{

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"required": false,

"schema": {

"title": "Response Format",

"type": "string",

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"default": "json"

},

"name": "response_format",

"in": "query"

},

{

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"required": false,

"schema": {

"title": "Email Address",

"type": "string",

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"format": "email",

"default": ""

},

"name": "email_address",

"in": "query"

},

{

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"required": false,

"schema": {

"title": "Response Fields",

"pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",

"type": "string",

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"default": ""

},

"name": "response_fields",

"in": "query"

},

{

"description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name. The set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).",

"required": false,

"schema": {

"title": "Sort",

"pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",

"type": "string",

"description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name. The set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).",

"default": ""

},

"name": "sort",

"in": "query"

},

{

"description": "Sets a numerical limit on the number of entries returned. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.",

"required": false,

"schema": {

"title": "Page Limit",

"minimum": 0.0,

"type": "integer",

"description": "Sets a numerical limit on the number of entries returned. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.",

"default": 20

},

"name": "page_limit",

"in": "query"

},

{

"description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",

"required": false,

"schema": {

"title": "Page Offset",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",

"default": 0

},

"name": "page_offset",

"in": "query"

},

{

"description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",

"required": false,

"schema": {

"title": "Page Number",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",

"default": 0

},

"name": "page_number",

"in": "query"

},

{

"description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",

"required": false,

"schema": {

"title": "Page Cursor",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",

"default": 0

},

"name": "page_cursor",

"in": "query"

},

{

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",

"required": false,

"schema": {

"title": "Page Above",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",

"default": 0

},

"name": "page_above",

"in": "query"

},

{

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",

"required": false,

"schema": {

"title": "Page Below",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",

"default": 0

},

"name": "page_below",

"in": "query"

},

{

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"required": false,

"schema": {

"title": "Include",

"type": "string",

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"default": "references"

},

"name": "include",

"in": "query"

}

],

"responses": {

"200": {

"description": "Successful Response",

"content": {

"application/json": {

"schema": {

"title": "Response Get References V0 References Get",

"anyOf": [

{

"$ref": "#/components/schemas/ReferenceResponseMany"

},

{

"$ref": "#/components/schemas/ErrorResponse"

}

]

}

}

}

},

"422": {

"description": "Validation Error",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/HTTPValidationError"

}

}

}

}

}

}

},

"/v0/references/{entry_id}": {

"get": {

"tags": [

"References"

],

"summary": "Get Single Reference",

"operationId": "get_single_reference_v0_references__entry_id__get",

"parameters": [

{

"required": true,

"schema": {

"title": "Entry Id",

"type": "string"

},

"name": "entry_id",

"in": "path"

},

{

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"required": false,

"schema": {

"title": "Response Format",

"type": "string",

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"default": "json"

},

"name": "response_format",

"in": "query"

},

{

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"required": false,

"schema": {

"title": "Email Address",

"type": "string",

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"format": "email",

"default": ""

},

"name": "email_address",

"in": "query"

},

{

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"required": false,

"schema": {

"title": "Response Fields",

"pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",

"type": "string",

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"default": ""

},

"name": "response_fields",

"in": "query"

},

{

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"required": false,

"schema": {

"title": "Include",

"type": "string",

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"default": "references"

},

"name": "include",

"in": "query"

}

],

"responses": {

"200": {

"description": "Successful Response",

"content": {

"application/json": {

"schema": {

"title": "Response Get Single Reference V0 References Entry Id Get",

"anyOf": [

{

"$ref": "#/components/schemas/ReferenceResponseOne"

},

{

"$ref": "#/components/schemas/ErrorResponse"

}

]

}

}

}

},

"422": {

"description": "Validation Error",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/HTTPValidationError"

}

}

}

}

}

}

},

"/v0/structures": {

"get": {

"tags": [

"Structures"

],

"summary": "Get Structures",

"operationId": "get_structures_v0_structures_get",

"parameters": [

{

"description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).",

"required": false,

"schema": {

"title": "Filter",

"type": "string",

"description": "A filter string, in the format described in section [API Filtering Format Specification](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#api-filtering-format-specification) of the [OPTIMADE spec](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst).",

"default": ""

},

"name": "filter",

"in": "query"

},

{

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"required": false,

"schema": {

"title": "Response Format",

"type": "string",

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"default": "json"

},

"name": "response_format",

"in": "query"

},

{

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"required": false,

"schema": {

"title": "Email Address",

"type": "string",

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"format": "email",

"default": ""

},

"name": "email_address",

"in": "query"

},

{

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"required": false,

"schema": {

"title": "Response Fields",

"pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",

"type": "string",

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"default": ""

},

"name": "response_fields",

"in": "query"

},

{

"description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name. The set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).",

"required": false,

"schema": {

"title": "Sort",

"pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",

"type": "string",

"description": "If supporting sortable queries, an implementation MUST use the `sort` query parameter with format as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-sorting).\n\nAn implementation MAY support multiple sort fields for a single query. If it does, it again MUST conform to the JSON API 1.0 specification.\n\nIf an implementation supports sorting for an [entry listing endpoint](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-endpoints), then the `/info/<entries>` endpoint MUST include, for each field name `<fieldname>` in its `data.properties.<fieldname>` response value that can be used for sorting, the key `sortable` with value `true`. If a field name under an entry listing endpoint supporting sorting cannot be used for sorting, the server MUST either leave out the `sortable` key or set it equal to `false` for the specific field name. The set of field names, with `sortable` equal to `true` are allowed to be used in the \"sort fields\" list according to its definition in the JSON API 1.0 specification. The field `sortable` is in addition to each property description (and the OPTIONAL field `unit`). An example is shown in section [Entry Listing Info Endpoints](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#entry-listing-info-endpoints).",

"default": ""

},

"name": "sort",

"in": "query"

},

{

"description": "Sets a numerical limit on the number of entries returned. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.",

"required": false,

"schema": {

"title": "Page Limit",

"minimum": 0.0,

"type": "integer",

"description": "Sets a numerical limit on the number of entries returned. See [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-pagination). The API implementation MUST return no more than the number specified. It MAY return fewer. The database MAY have a maximum limit and not accept larger numbers (in which case an error code -- 403 Forbidden -- MUST be returned). The default limit value is up to the API implementation to decide.\n\nA server MUST implement pagination in the case of no user-specified `sort` parameter (via the `links` response field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields)). A server MAY implement pagination in concert with `sort`.",

"default": 20

},

"name": "page_limit",

"in": "query"

},

{

"description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",

"required": false,

"schema": {

"title": "Page Offset",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _offset-based_ pagination: using `page_offset` and `page_limit` is RECOMMENDED.\n**Example**: Skip 50 structures and fetch up to 100: `/structures?page_offset=50&page_limit=100`.",

"default": 0

},

"name": "page_offset",

"in": "query"

},

{

"description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",

"required": false,

"schema": {

"title": "Page Number",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _page-based_ pagination: using `page_number` and `page_limit` is RECOMMENDED. It is RECOMMENDED that the first page has number 1, i.e., that `page_number` is 1-based.\n**Example**: Fetch page 2 of up to 50 structures per page: `/structures?page_number=2&page_limit=50`.",

"default": 0

},

"name": "page_number",

"in": "query"

},

{

"description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",

"required": false,

"schema": {

"title": "Page Cursor",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _cursor-based_ pagination: using `page_cursor` and `page_limit` is RECOMMENDED.",

"default": 0

},

"name": "page_cursor",

"in": "query"

},

{

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",

"required": false,

"schema": {

"title": "Page Above",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.\n**Example**: Fetch up to 100 structures above sort-field value 4000 (in this example, server chooses to fetch results sorted by increasing id, so `page_above` value refers to an `id` value): `/structures?page_above=4000&page_limit=100`.",

"default": 0

},

"name": "page_above",

"in": "query"

},

{

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",

"required": false,

"schema": {

"title": "Page Below",

"minimum": 0.0,

"type": "integer",

"description": "RECOMMENDED for use with _value-based_ pagination: using `page_above`/`page_below` and `page_limit` is RECOMMENDED.",

"default": 0

},

"name": "page_below",

"in": "query"

},

{

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"required": false,

"schema": {

"title": "Include",

"type": "string",

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"default": "references"

},

"name": "include",

"in": "query"

}

],

"responses": {

"200": {

"description": "Successful Response",

"content": {

"application/json": {

"schema": {

"title": "Response Get Structures V0 Structures Get",

"anyOf": [

{

"$ref": "#/components/schemas/StructureResponseMany"

},

{

"$ref": "#/components/schemas/ErrorResponse"

}

]

}

}

}

},

"422": {

"description": "Validation Error",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/HTTPValidationError"

}

}

}

}

}

}

},

"/v0/structures/{entry_id}": {

"get": {

"tags": [

"Structures"

],

"summary": "Get Single Structure",

"operationId": "get_single_structure_v0_structures__entry_id__get",

"parameters": [

{

"required": true,

"schema": {

"title": "Entry Id",

"type": "string"

},

"name": "entry_id",

"in": "path"

},

{

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"required": false,

"schema": {

"title": "Response Format",

"type": "string",

"description": "The output format requested (see section [Response Format](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#response-format) in the spec). Defaults to the format string 'json', which specifies the standard output format described in this specification.\n**Example**: http://example.com/v1/structures?response_format=xml",

"default": "json"

},

"name": "response_format",

"in": "query"

},

{

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"required": false,

"schema": {

"title": "Email Address",

"type": "string",

"description": "An email address of the user making the request. The email SHOULD be that of a person and not an automatic system.\n**Example**: http://example.com/v1/structures?email_address=user@example.com",

"format": "email",

"default": ""

},

"name": "email_address",

"in": "query"

},

{

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"required": false,

"schema": {

"title": "Response Fields",

"pattern": "([a-z_][a-z_0-9]*(,[a-z_][a-z_0-9]*)*)?",

"type": "string",

"description": "A comma-delimited set of fields to be provided in the output. If provided, these fields MUST be returned along with the REQUIRED fields. Other OPTIONAL fields MUST NOT be returned when this parameter is present.\n**Example**: http://example.com/v1/structures?response_fields=last_modified,nsites",

"default": ""

},

"name": "response_fields",

"in": "query"

},

{

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"required": false,

"schema": {

"title": "Include",

"type": "string",

"description": "The JSON API concept of returning [compound documents](https://jsonapi.org/format/1.0/#document-compound-documents) by utilizing the `include` query parameter as specified by [JSON API 1.0](https://jsonapi.org/format/1.0/#fetching-includes).\n\nAll related resource objects MUST be returned as part of an array value for the top-level `included` field, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\nThe value of `include` MUST be a comma-separated list of \"relationship paths\", as defined in the [JSON API](https://jsonapi.org/format/1.0/#fetching-includes). If relationship paths are not supported, or a server is unable to identify a relationship path a `400 Bad Request` response MUST be made.\n\nThe **default value** for `include` is `references`. This means `references` entries MUST always be included under the top-level field `included` as default, since a server assumes if `include` is not specified by a client in the request, it is still specified as `include=references`. Note, if a client explicitly specifies `include` and leaves out `references`, `references` resource objects MUST NOT be included under the top-level field `included`, as per the definition of `included`, see section [JSON Response Schema: Common Fields](https://github.com/Materials-Consortia/OPTIMADE/blob/develop/optimade.rst#json-response-schema-common-fields).\n\n- **Note**: A query with the parameter `include` set to the empty string means no related resource objects are to be returned under the top-level field `included`.",

"default": "references"

},

"name": "include",

"in": "query"

}

],

"responses": {

"200": {

"description": "Successful Response",

"content": {

"application/json": {

"schema": {

"title": "Response Get Single Structure V0 Structures Entry Id Get",

"anyOf": [

{

"$ref": "#/components/schemas/StructureResponseOne"

},

{

"$ref": "#/components/schemas/ErrorResponse"

}

]

}

}

}

},

"422": {

"description": "Validation Error",

"content": {

"application/json": {

"schema": {

"$ref": "#/components/schemas/HTTPValidationError"

}

}

}

}

}

}

}

},

"components": {

"schemas": {

"Assembly": {

"title": "Assembly",

"required": [

"sites_in_groups",

"group_probabilities"

],

"type": "object",

"properties": {

"sites_in_groups": {

"title": "Sites In Groups",

"type": "array",

"items": {

"type": "array",

"items": {

"type": "integer"

}

},

"description": "Index of the sites (0-based) that belong to each group for each assembly.\n\nExample: :val:`[[1], [2]]`: two groups, one with the second site, one with the third.\nExample: :val:`[[1,2], [3]]`: one group with the second and third site, one with the fourth."

},

"group_probabilities": {

"title": "Group Probabilities",

"type": "array",

"items": {

"type": "number"

},

"description": "Statistical probability of each group. It MUST have the same length as :property:`sites_in_groups`.\nIt SHOULD sum to one.\nSee below for examples of how to specify the probability of the occurrence of a vacancy.\nThe possible reasons for the values not to sum to one are the same as already specified above for the :property:`concentration` of each :property:`species`, see property `species`_."

}

},

"description": "A description of groups of sites that are statistically correlated.\n\n- **Examples** (for each entry of the assemblies list):\n\n - :val:`{\"sites_in_groups\": [[0], [1]], \"group_probabilities: [0.3, 0.7]}`: the first site and the second site never occur at the same time in the unit cell.\n Statistically, 30 % of the times the first site is present, while 70 % of the times the second site is present.\n - :val:`{\"sites_in_groups\": [[1,2], [3]], \"group_probabilities: [0.3, 0.7]}`: the second and third site are either present together or not present; they form the first group of atoms for this assembly.\n The second group is formed by the fourth site.\n Sites of the first group (the second and the third) are never present at the same time as the fourth site.\n 30 % of times sites 1 and 2 are present (and site 3 is absent); 70 % of times site 3 is present (and sites 1 and 2 are absent)."

},

"Attributes": {

"title": "Attributes",

"type": "object",

"properties": {},

"description": "Members of the attributes object (\"attributes\") represent information about the resource object in which it's defined.\nThe keys for Attributes MUST NOT be:\n relationships\n links\n id\n type"

},

"AvailableApiVersion": {

"title": "AvailableApiVersion",

"required": [

"url",

"version"

],

"type": "object",

"properties": {

"url": {

"title": "Url",

"maxLength": 65536,

"minLength": 1,

"pattern": ".+/v[0-1](\\.[0-9]+)*/?$",

"type": "string",

"description": "a string specifying a versioned base URL that MUST adhere to the rules in section Base URL",

"format": "uri"

},

"version": {

"title": "Version",

"pattern": "^[0-9]+(\\.[0-9]+){,2}$",

"type": "string",

"description": "a string containing the full version number of the API served at that versioned base URL. The version number string MUST NOT be prefixed by, e.g., 'v'."

}

},

"description": "A JSON object containing information about an available API version"

},

"BaseInfoAttributes": {

"title": "BaseInfoAttributes",

"required": [

"api_version",

"available_api_versions",

"available_endpoints",

"entry_types_by_format"

],

"type": "object",

"properties": {

"api_version": {

"title": "Api Version",

"type": "string",

"description": "Presently used version of the OPTIMADE API"

},

"available_api_versions": {

"title": "Available Api Versions",

"type": "array",

"items": {

"$ref": "#/components/schemas/AvailableApiVersion"

},

"description": "A list of dictionaries of available API versions at other base URLs"

},

"formats": {

"title": "Formats",

"type": "array",

"items": {

"type": "string"

},

"description": "List of available output formats.",

"default": [

"json"

]

},

"available_endpoints": {

"title": "Available Endpoints",

"type": "array",

"items": {

"type": "string"

},

"description": "List of available endpoints (i.e., the string to be appended to the versioned base URL)."

},

"entry_types_by_format": {

"title": "Entry Types By Format",

"type": "object",

"additionalProperties": {

"type": "array",

"items": {

"type": "string"

}

},

"description": "Available entry endpoints as a function of output formats."

},

"is_index": {

"title": "Is Index",

"type": "boolean",

"description": "If true, this is an index meta-database base URL (see section Index Meta-Database). If this member is not provided, the client MUST assume this is not an index meta-database base URL (i.e., the default is for is_index to be false).",

"default": false

}

},

"description": "Attributes for Base URL Info endpoint"

},

"BaseInfoResource": {

"title": "BaseInfoResource",

"required": [

"attributes"