Search Compounds

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +false

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "results",
+      "searchType",
+      "offset"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `missing_identifier_args`: searchType is \"identifier\" but identifierType or identifiers were omitted `missing_formula`: searchType is \"formula\" but the formula field was omitted `missing_structure_args`: substructure/superstructure/similarity search missing query or queryType `invalid_cid_query`: structure/similarity search with queryType \"cid\" but query is not a positive integer CID Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "missing_identifier_args",
+            "missing_formula",
+            "missing_structure_args",
+            "invalid_cid_query"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

Removed value: -[
-  "results",
-  "searchType",
-  "offset"
-]

Previous value: -"Maximum CIDs to return (1-200). Default: 20."New value: +"Maximum CIDs to return per page (1-200). Use offset to reach matches past this page. Default: 20."

Previous value: -"number"New value: +"integer"

Added value: +{
+  "default": 0,
+  "description": "Zero-based index of the first CID to return. Pass the nextOffset from a previous call to read the following page. Identifier lookups resolve every match up front, so paging them is free; formula, substructure, superstructure, and similarity searches have to ask PubChem for offset + maxResults records to reach a page, so deep pages cost progressively more upstream — hence the 10000 ceiling. Default: 0.",
+  "maximum": 10000,
+  "minimum": 0,
+  "type": "integer"
+}

Added value: +{
+  "description": "Offset to pass on the next call to continue past this page. Omitted when no further matches remain.",
+  "type": "number"
+}

Previous value: -"Recovery guidance when no compounds matched — echoes search strategy and suggests how to broaden. Absent when results were returned."New value: +"Recovery guidance when no compounds matched, when the offset runs past the matches observed, when identifiers failed to resolve, or when further pages remain. Absent when this page is complete and every identifier resolved."

Added value: +{
+  "description": "Zero-based index of the first CID returned.",
+  "type": "number"
+}

Previous value: -"CIDs returned after the maxResults cap."New value: +"CIDs returned on this page."

Previous value: -"Total CIDs found before the maxResults cap."New value: +"Exact number of matching CIDs across all pages. Omitted when a formula, substructure, superstructure, or similarity search saturated the records it requested — PubChem returns no match count for those, so totalFoundAtLeast reports a floor instead."

Added value: +{
+  "description": "Lower bound on matching CIDs, reported in place of totalFound when the exact count is unavailable. At least this many match, and the true total may be higher; page further with offset to observe more.",
+  "type": "number"
+}

Previous value: -"True when CIDs were capped at maxResults — more matches exist than returned."New value: +"True when matching CIDs remain past this page."

Previous value: -[
-  "results",
-  "searchType",
-  "totalFound"
-]New value: +[
+  "results",
+  "searchType",
+  "offset"
+]

Added value: +{
+  "description": "Identifier-mode only: input identifiers that resolved to no CID. Omitted when every identifier resolved and for non-identifier searches.",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

Added value: +{
+  "description": "The maxResults cap that was applied.",
+  "type": "number"
+}

Added value: +{
+  "description": "CIDs returned after the maxResults cap.",
+  "type": "number"
+}

Added value: +{
+  "description": "True when CIDs were capped at maxResults — more matches exist than returned.",
+  "type": "boolean"
+}

Previous value: -"Required for identifier search. Array of identifiers to resolve (1-25). Examples: [\"aspirin\", \"ibuprofen\"] for name, [\"CC(=O)OC1=CC=CC=C1C(=O)O\"] for SMILES."New value: +"Required for identifier search. Array of identifiers to resolve (1-25). Examples: [\"aspirin\", \"ibuprofen\"] for name, [\"CC(=O)OC1=CC=CC=C1C(=O)O\"] for SMILES, [\"BSYNRYMUTXBXSQ-UHFFFAOYSA-N\"] for inchikey (27-char block format)."

Previous value: -"Required for substructure/superstructure/similarity searches. A SMILES string or PubChem CID (as string) for the query structure."New value: +"Required for substructure/superstructure/similarity searches. A SMILES string (e.g. \"CC(=O)O\") or PubChem CID as a string (e.g. \"2244\")."

Previous value: -"Search strategy: \"identifier\" (name/SMILES/InChIKey lookup), \"formula\", \"substructure\", \"superstructure\", or \"similarity\"."New value: +"Search strategy. \"identifier\": name/SMILES/InChIKey lookup. \"formula\": molecular formula. \"substructure\": find compounds containing the query as a substructure. \"superstructure\": find compounds that are themselves substructures of the query. \"similarity\": 2D Tanimoto similarity to the query."

Added value: +{
+  "description": "Recovery guidance when no compounds matched — echoes search strategy and suggests how to broaden. Absent when results were returned.",
+  "type": "string"
+}

Added value: +"Matching compound entry."

Previous value: -"Compound properties when requested."New value: +"Compound properties keyed by name (echoes input.properties; only present when requested)."

Previous value: -"The search strategy used."New value: +"Search strategy used: identifier, formula, substructure, superstructure, or similarity."

Previous value: -"Total CIDs found (before maxResults cap)."New value: +"Total CIDs found before the maxResults cap."

Previous value: -[
-  "searchType",
-  "totalFound",
-  "results"
-]New value: +[
+  "results",
+  "searchType",
+  "totalFound"
+]