{"openapi":"3.1.0","info":{"title":"ChemSpider (BYOK) API","version":"0.1.0","description":"ChemSpider (BYOK) lets an AI assistant read your own ChemSpider data through the ChemSpider API with a key you supply (RSC Compounds API key). Read-only: 9 tools (search_by_name, search_by_formula, search_by_mass, get_search_status, get_search_results, get_compound, get_external_references, list_data_sources, convert_identifier). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-chemspider.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-chemspider/docs"},"termsOfService":"https://connectorbay.com/byok-chemspider/terms"},"servers":[{"url":"https://byok-chemspider.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-chemspider/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/search_by_name":{"post":{"operationId":"search_by_name","summary":"Start a ChemSpider search by compound name (3 to 4000 characters). Returns a query id; then call get_search_status and g","description":"Start a ChemSpider search by compound name (3 to 4000 characters). Returns a query id; then call get_search_status and get_search_results with it. Use for \"Find the ChemSpider records for aspirin\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"name":{"description":"Compound name, at least 3 characters, for example 'aspirin'.","maxLength":200,"title":"Name","type":"string"},"order_by":{"anyOf":[{"enum":["default","recordId","massDefect","molecularWeight","referenceCount","dataSourceCount","pubMedCount","rscCount"],"type":"string"},{"type":"null"}],"default":"default","description":"Sort the matches by: default, recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount or rscCount.","title":"Order By"},"order_direction":{"anyOf":[{"enum":["default","ascending","descending"],"type":"string"},{"type":"null"}],"default":"default","description":"Sort direction: default, ascending or descending.","title":"Order Direction"}},"required":["name"],"title":"search_by_nameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_by_formula":{"post":{"operationId":"search_by_formula","summary":"Start a ChemSpider search by molecular formula. Returns a query id; then call get_search_status and get_search_results w","description":"Start a ChemSpider search by molecular formula. Returns a query id; then call get_search_status and get_search_results with it. Use for \"Which compounds have the formula C5H5N\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"formula":{"description":"Molecular formula, for example 'C5H5N'.","maxLength":50,"title":"Formula","type":"string"},"order_by":{"anyOf":[{"enum":["default","recordId","massDefect","molecularWeight","referenceCount","dataSourceCount","pubMedCount","rscCount"],"type":"string"},{"type":"null"}],"default":"default","description":"Sort the matches by: default, recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount or rscCount.","title":"Order By"},"order_direction":{"anyOf":[{"enum":["default","ascending","descending"],"type":"string"},{"type":"null"}],"default":"default","description":"Sort direction: default, ascending or descending.","title":"Order Direction"}},"required":["formula"],"title":"search_by_formulaArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/search_by_mass":{"post":{"operationId":"search_by_mass","summary":"Start a ChemSpider search by monoisotopic mass within a tolerance range. Returns a query id; then call get_search_status","description":"Start a ChemSpider search by monoisotopic mass within a tolerance range. Returns a query id; then call get_search_status and get_search_results with it. Use for \"Which compounds have a monoisotopic mass of about 164.1062\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"mass":{"description":"Monoisotopic mass (1 to 11000).","maximum":11000,"minimum":1,"title":"Mass","type":"number"},"mass_range":{"description":"Allowed deviation plus or minus (0.0001 to 100).","maximum":100,"minimum":0.0001,"title":"Mass Range","type":"number"},"component":{"anyOf":[{"enum":["any","single","multiple"],"type":"string"},{"type":"null"}],"default":"any","description":"Count single-component compounds only, multi-component only, or any.","title":"Component"},"order_by":{"anyOf":[{"enum":["default","recordId","massDefect","molecularWeight","referenceCount","dataSourceCount","pubMedCount","rscCount"],"type":"string"},{"type":"null"}],"default":"default","description":"Sort the matches by: default, recordId, massDefect, molecularWeight, referenceCount, dataSourceCount, pubMedCount or rscCount.","title":"Order By"},"order_direction":{"anyOf":[{"enum":["default","ascending","descending"],"type":"string"},{"type":"null"}],"default":"default","description":"Sort direction: default, ascending or descending.","title":"Order Direction"}},"required":["mass","mass_range"],"title":"search_by_massArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_search_status":{"post":{"operationId":"get_search_status","summary":"Check whether a ChemSpider search started with a search tool is finished (status Queued, Processing, PartialResults, Com","description":"Check whether a ChemSpider search started with a search tool is finished (status Queued, Processing, PartialResults, Complete, Failed or NotFound) and how many records it found. Use for \"Is my ChemSpider search finished\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query_id":{"description":"Query id returned by a search tool (a 32 to 36 character id).","maxLength":40,"title":"Query Id","type":"string"}},"required":["query_id"],"title":"get_search_statusArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_search_results":{"post":{"operationId":"get_search_results","summary":"Get the ChemSpider record ids found by a finished search (call get_search_status first); look the ids up with get_compou","description":"Get the ChemSpider record ids found by a finished search (call get_search_status first); look the ids up with get_compound. Use for \"Show the record ids found by my ChemSpider search\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query_id":{"description":"Query id returned by a search tool (a 32 to 36 character id).","maxLength":40,"title":"Query Id","type":"string"},"start":{"anyOf":[{"maximum":1000000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Zero-based index of the first id to return.","title":"Start"},"count":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many ids to return (1 to 100).","title":"Count"}},"required":["query_id"],"title":"get_search_resultsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_compound":{"post":{"operationId":"get_compound","summary":"Get a ChemSpider compound record by record id: common name, formula, SMILES, InChI, InChIKey, masses and reference count","description":"Get a ChemSpider compound record by record id: common name, formula, SMILES, InChI, InChIKey, masses and reference counts for the requested fields. Use for \"What are the formula, SMILES and InChIKey of ChemSpider record 2157\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"record_id":{"description":"ChemSpider record id, a whole number such as 2157.","maximum":2000000000,"minimum":1,"title":"Record Id","type":"integer"},"fields":{"description":"Comma-separated fields to return: SMILES, Formula, InChI, InChIKey, StdInChI, StdInChIKey, AverageMass, MolecularWeight, MonoisotopicMass, NominalMass, CommonName, ReferenceCount, DataSourceCount, PubMedCount, RSCCount (Mol2D and Mol3D return large molfiles).","maxLength":300,"title":"Fields","type":"string"}},"required":["record_id","fields"],"title":"get_compoundArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_external_references":{"post":{"operationId":"get_external_references","summary":"List the external database records (source, external id and link) that a ChemSpider compound is cross-referenced to. Use","description":"List the external database records (source, external id and link) that a ChemSpider compound is cross-referenced to. Use for \"Which other databases list ChemSpider record 2157\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"record_id":{"description":"ChemSpider record id, a whole number such as 2157.","maximum":2000000000,"minimum":1,"title":"Record Id","type":"integer"}},"required":["record_id"],"title":"get_external_referencesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_data_sources":{"post":{"operationId":"list_data_sources","summary":"List the names of the chemical databases ChemSpider aggregates, usable to restrict searches. Use for \"Which data sources","description":"List the names of the chemical databases ChemSpider aggregates, usable to restrict searches. Use for \"Which data sources does ChemSpider cover\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_data_sourcesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/convert_identifier":{"post":{"operationId":"convert_identifier","summary":"Convert a chemical identifier between InChI, InChIKey, Mol and SMILES formats. Use for \"Convert the SMILES CC(=O)Oc1cccc","description":"Convert a chemical identifier between InChI, InChIKey, Mol and SMILES formats. Use for \"Convert the SMILES CC(=O)Oc1ccccc1C(=O)O to an InChIKey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"input":{"description":"The identifier text to convert, for example a SMILES string.","maxLength":4000,"title":"Input","type":"string"},"input_format":{"description":"Format of the input: InChI, InChIKey, Mol or SMILES.","enum":["InChI","InChIKey","Mol","SMILES"],"title":"Input Format","type":"string"},"output_format":{"description":"Format wanted: InChI, InChIKey, Mol or SMILES.","enum":["InChI","InChIKey","Mol","SMILES"],"title":"Output Format","type":"string"}},"required":["input","input_format","output_format"],"title":"convert_identifierArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}