online documentation

User Tools

Site Tools

Trace: • faq • api
api

This is an old revision of the document!

Table of Contents

API base url: https://mcule.com/api/v1/

Examples are demonstrated with HTTPie.

Response status codes

  • 200 OK - Success response
  • 400 BAD REQUEST - A validation error typically
  • 401 UNAUTHORIZED - Unauthorized
  • 403 FORBIDDEN - Permission denied
  • 404 NOT FOUND - Not found
  • 500 SERVER ERROR - Something went wrong

Public API endpoints

Public API endpoints are accessible to everyone, without authentication.

Database files

Endpoint:
/database-files/
Example API request:
http https://mcule.com/api/v1/database-files/ --print HBhb
Request:
GET /api/v1/database-files/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Response:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json

{
    "count": 2, 
    "next": null, 
    "previous": null, 
    "results": [
        {
            "description": "All purchasable, in stock & virtual compounds", 
            "entry_count": 35772718, 
            "files": [
                {
                    "download_url": "https://mcule.s3.amazonaws.com/database/mcule_purchasable_full_170918.sdf.gz", 
                    "file_type": "sdf.gz", 
                    "file_type_display": "2D SDF (sdf.gz)", 
                    "size_mb": 5762
                }, 
                {
                    "download_url": "https://mcule.s3.amazonaws.com/database/mcule_purchasable_full_170918.smiles.gz", 
                    "file_type": "smiles.gz", 
                    "file_type_display": "SMILES (smi.gz)", 
                    "size_mb": 462
                }
            ], 
            "last_updated": "2017-09-18", 
            "name": "Mcule Purchasable (full)"
        }, 
        {
            "description": "All purchasable, in stock compounds", 
            "entry_count": 5648837, 
            "files": [
                {
                    "download_url": "https://mcule.s3.amazonaws.com/database/mcule_purchasable_in_stock_170918.sdf.gz", 
                    "file_type": "sdf.gz", 
                    "file_type_display": "2D SDF (sdf.gz)", 
                    "size_mb": 1311
                }, 
                {
                    "download_url": "https://mcule.s3.amazonaws.com/database/mcule_purchasable_in_stock_170918.smiles.gz", 
                    "file_type": "smiles.gz", 
                    "file_type_display": "SMILES (smi.gz)", 
                    "size_mb": 84
                }
            ], 
            "last_updated": "2017-09-18", 
            "name": "Mcule Purchasable (in stock)"
        }
    ]
}

Compound details

Endpoint:
/compound/<mcule_id>/
Example API request:
http https://mcule.com/api/v1/compound/MCULE-9380369173/ --print HBhb
Request:
GET /api/v1/compound/MCULE-9380369173/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Response:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Content-Encoding: gzip
Content-Type: application/json

{
    "components": [], 
    "formula": "C15H11N3O2S2", 
    "inchi_key": "WVRLGAPZMSKMGL-UHFFFAOYSA-N", 
    "mcule_id": "MCULE-9380369173", 
    "mol": "\n  mcule   05121714262D\n\n 22 24  0  0  0  0  0  0  0  0999 V2000\n    3.8489    4.0497    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    3.8489    3.0496    0.0000 O   0  0  0  0  0  0  0  0  0  0  0  0\n    2.9831    2.5496    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    2.1169    3.0496    0.0000 O   0  0  0  0  0  0  0  0  0  0  0  0\n    2.9831    1.5495    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    3.7922    0.9621    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    3.4832    0.0109    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n    2.4829    0.0109    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    1.8951   -0.7981    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.9006   -0.6935    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.3127   -1.5025    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n    0.6220   -2.4537    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -0.1871   -3.0416    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n   -0.9960   -2.4537    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -0.6872   -1.5025    0.0000 S   0  0  0  0  0  0  0  0  0  0  0  0\n   -1.9472   -2.7625    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -2.1550   -3.7409    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -3.1061   -4.0497    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -3.8489   -3.3807    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -3.6412   -2.4024    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\n   -2.6901   -2.0935    0.0000 N   0  0  0  0  0  0  0  0  0  0  0  0\n    2.1740    0.9621    0.0000 S   0  0  0  0  0  0  0  0  0  0  0  0\n  1  2  1  0  0  0  0\n  2  3  1  0  0  0  0\n  3  4  2  0  0  0  0\n  3  5  1  0  0  0  0\n  5  6  2  0  0  0  0\n  6  7  1  0  0  0  0\n  7  8  2  0  0  0  0\n  8  9  1  0  0  0  0\n  9 10  2  3  0  0  0\n 10 11  1  0  0  0  0\n 11 12  2  0  0  0  0\n 12 13  1  0  0  0  0\n 13 14  2  0  0  0  0\n 14 15  1  0  0  0  0\n 11 15  1  0  0  0  0\n 14 16  1  0  0  0  0\n 16 17  1  0  0  0  0\n 17 18  2  0  0  0  0\n 18 19  1  0  0  0  0\n 19 20  2  0  0  0  0\n 20 21  1  0  0  0  0\n 16 21  2  0  0  0  0\n  8 22  1  0  0  0  0\n  5 22  1  0  0  0  0\nM  END", 
    "properties": {
        "atoms": 33, 
        "components": 1, 
        "ct_bonds": 1, 
        "h_bond_acceptors": 5, 
        "h_bond_donors": 0, 
        "halogen_atoms": 0, 
        "heavy_atoms": 22, 
        "heteroatoms": 7, 
        "hydrogens": 11, 
        "known_ct_bonds": 0, 
        "known_stereocenters": 0, 
        "logp": 3.6186, 
        "mol_mass": 329.401, 
        "non_organic_atoms": 0, 
        "o_and_n_atoms": 5, 
        "psa": 121.45, 
        "r3_violations": 5, 
        "r5_violations": 0, 
        "refractivity": 87.6665, 
        "rings": 3, 
        "rotatable_bonds": 5, 
        "stereocenters": 0, 
        "undef_ct_bonds": 0, 
        "undef_stereocenters": 0, 
        "unknown_ct_bonds": 1, 
        "unknown_stereocenters": 0
    }, 
    "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", 
    "std_inchi": "InChI=1S/C15H11N3O2S2/c1-20-15(19)12-9-17-13(22-12)6-5-10-8-18-14(21-10)11-4-2-3-7-16-11/h2-9H,1H3", 
    "stereo_type": "none", 
    "url": "https://mcule.com/MCULE-9380369173/"
}

InChIKey lookup

Endpoint:
/lookup/<inchi_key>
Example API request:
http https://mcule.com/api/v1/lookup/inchikey/WVRLGAPZMSKMGL-UHFFFAOYSA-N --print HBhb
Request:
GET /api/v1/lookup/inchikey/WVRLGAPZMSKMGL-UHFFFAOYSA-N HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Response:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Content-Encoding: gzip
Content-Type: application/json

{
    "results": [
        {
            "mcule_id": "MCULE-9380369173", 
            "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", 
            "url": "https://mcule.com/MCULE-9380369173/"
        }
    ]
}

Single query search / lookup

Endpoint:
/search/lookup/?query=<your_query>

Where the query can be an mcule ID, SMILES, InChI or InChIKey identifier.

Example API request:
http 'https://mcule.com/api/v1/search/lookup/?query=COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O' --print HBhb
Request:
GET /api/v1/search/lookup/?query=COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Response:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Content-Encoding: gzip
Content-Type: application/json

{
    "results": [
        {
            "mcule_id": "MCULE-9380369173", 
            "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", 
            "url": "https://mcule.com/MCULE-9380369173/"
        }
    ]
}

Authentication

Authentication is currently a token based authentication. If you would like to access our protected API endpoints, please drop us an email at info@mcule.com and we can provide you with a token.

Once you have a valid token you have to send it in the Authorization header: 

Authorization: Token <your_token>

Protected API endpoints

Protected API endpoints are only accessible if a valid token is provided in the Authorization header of the request.

Compound availability

Endpoint:
/compound/<mcule_id>/availability/
Example API request:
http https://mcule.com/api/v1/compound/MCULE-9380369173/availability/ "Authorization: Token <your_token>" --print HBhb
Request:
GET /api/v1/compound/MCULE-9380369173/availability/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Token <your_token>
Response:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Content-Encoding: gzip
Content-Type: application/json

{
    "availability_type": "in stock", 
    "confirmed_amount": 242, 
    "confirmed_amount_unit": "mg"
}

Compound prices

Endpoint:
/compound/<mcule_id>/prices/
Example API request:
http https://mcule.com/api/v1/compound/MCULE-9380369173/prices/ "Authorization: Token <your_token>" --print HBhb
Request:
GET /api/v1/compound/MCULE-9380369173/prices/ HTTP/1.1
Accept: */*
Accept-Encoding: gzip, deflate
Authorization: Token <your_token>
Response:
HTTP/1.1 200 OK
Allow: GET, HEAD, OPTIONS
Content-Encoding: gzip
Content-Type: application/json

{
    "best_prices": [
        {
            "amount": 1, 
            "currency": "USD", 
            "delivery_time_working_days": 9, 
            "price": 107, 
            "purity": 90, 
            "unit": "mg"
        }, 
        {
            "amount": 5, 
            "currency": "USD", 
            "delivery_time_working_days": 9, 
            "price": 116, 
            "purity": 90, 
            "unit": "mg"
        }, 
        {
            "amount": 10, 
            "currency": "USD", 
            "delivery_time_working_days": 9, 
            "price": 151, 
            "purity": 90, 
            "unit": "mg"
        }
    ]
}

It returns the best prices for 1mg, 5mg and 10mg amounts by default. You can specify amounts of your choice in the amounts GET parameter: 

http 'https://mcule.com/api/v1/compound/MCULE-9380369173/prices/?amounts=15,20' "Authorization: Token <your_token>" --print HBhb

Multiple queries exact search currently accepts the following input identifiers: mcule ID, SMILES, InChI or InChIKey identifiers.

Endpoint:
/search/exact/
Example API request:
echo '{"queries": ["COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1", "C1([C@H](C(C)C)NC(CCCCC2CCSS2)=O)NC2=C(C=CC=C2)N=1", "C1C=C(COC(C(O)(CC2C=CC(O)=CC=2)C(C)OC(C(O)(CC2C=CC(O)=CC=2)C(C)OC(C)=O)=O)=O)C=CC=1OC1C(O)C(O)C(O)C(CO)O1", "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1"]}' | http https://mcule.com/api/v1/search/exact/ "Authorization: Token <your_token>" --print HBhb
Request:
POST /api/v1/search/exact/ HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Token <your_token>
Content-Type: application/json

{
    "queries": [
        "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O",
        "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1",
        "C1([C@H](C(C)C)NC(CCCCC2CCSS2)=O)NC2=C(C=CC=C2)N=1",
"C1C=C(COC(C(O)(CC2C=CC(O)=CC=2)C(C)OC(C(O)(CC2C=CC(O)=CC=2)C(C)OC(C)=O)=O)=O)C=CC=1OC1C(O)C(O)C(O)C(CO)O1",
        "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1"
    ]
}
Response:
HTTP/1.1 200 OK
Allow: POST, OPTIONS
Content-Encoding: gzip
Content-Type: application/json

{
    "results": [
        {
            "input_index": 1, 
            "mcule_id": "MCULE-9380369173", 
            "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", 
            "url": "https://mcule.com/MCULE-9380369173/"
        }, 
        {
            "input_index": 2, 
            "mcule_id": "MCULE-4016901520", 
            "smiles": "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1", 
            "url": "https://mcule.com/MCULE-4016901520/"
        }, 
        {
            "input_index": 3, 
            "mcule_id": "MCULE-7428195288", 
            "smiles": "C1([C@H](C(C)C)NC(CCCC[C@H]2CCSS2)=O)NC2=C(C=CC=C2)N=1", 
            "url": "https://mcule.com/MCULE-7428195288/"
        }, 
        {
            "input_index": 5, 
            "mcule_id": "MCULE-1259420189", 
            "smiles": "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1", 
            "url": "https://mcule.com/MCULE-1259420189/"
        }
    ]
}

Multiple queries exact search with availability

Endpoint:
/search/exact/availability/
Example API request:
echo {"queries": ["COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1", "C1([C@H](C(C)C)NC(CCCCC2CCSS2)=O)NC2=C(C=CC=C2)N=1", "C1C=C(COC(C(O)(CC2C=CC(O)=CC=2)C(C)OC(C(O)(CC2C=CC(O)=CC=2)C(C)OC(C)=O)=O)=O)C=CC=1OC1C(O)C(O)C(O)C(CO)O1", "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1"]} | http https://mcule.com/api/v1/search/exact/availability/ "Authorization: Token <your_token>" --print HBhb
Request:
POST /api/v1/search/exact/availability/ HTTP/1.1
Accept: application/json
Accept-Encoding: gzip, deflate
Authorization: Token <your_token>
Content-Type: application/json

{
    "queries": [
        "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O",
        "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1",
        "C1([C@H](C(C)C)NC(CCCCC2CCSS2)=O)NC2=C(C=CC=C2)N=1",
"C1C=C(COC(C(O)(CC2C=CC(O)=CC=2)C(C)OC(C(O)(CC2C=CC(O)=CC=2)C(C)OC(C)=O)=O)=O)C=CC=1OC1C(O)C(O)C(O)C(CO)O1",
        "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1"
    ]
}
Response:
HTTP/1.1 200 OK
Allow: POST, OPTIONS
Content-Encoding: gzip
Content-Type: application/json

{
    "results": [
        {
            "availability": {
                "availability_type": "in stock", 
                "confirmed_amount": 242, 
                "confirmed_amount_unit": "mg"
            }, 
            "input_index": 1, 
            "mcule_id": "MCULE-9380369173", 
            "smiles": "COC(C1SC(C=CC2SC(C3=NC=CC=C3)=NC=2)=NC=1)=O", 
            "url": "https://mcule.com/MCULE-9380369173/"
        }, 
        {
            "availability": {
                "availability_type": "in stock", 
                "confirmed_amount": null, 
                "confirmed_amount_unit": "mg"
            }, 
            "input_index": 2, 
            "mcule_id": "MCULE-4016901520", 
            "smiles": "CC1=C(C(N2CC3C(CCC3N)C2)=O)SC(CC2=CC=CC=C2)=N1", 
            "url": "https://mcule.com/MCULE-4016901520/"
        }, 
        {
            "availability": {
                "availability_type": "in stock", 
                "confirmed_amount": null, 
                "confirmed_amount_unit": "mg"
            }, 
            "input_index": 3, 
            "mcule_id": "MCULE-7428195288", 
            "smiles": "C1([C@H](C(C)C)NC(CCCC[C@H]2CCSS2)=O)NC2=C(C=CC=C2)N=1", 
            "url": "https://mcule.com/MCULE-7428195288/"
        }, 
        {
            "availability": {
                "availability_type": "potentially purchasable", 
                "confirmed_amount": null, 
                "confirmed_amount_unit": "mg"
            }, 
            "input_index": 5, 
            "mcule_id": "MCULE-1259420189", 
            "smiles": "CCCCC1=CC=C(CC(N(CC2CCN(C)CC2)C)=O)C=C1", 
            "url": "https://mcule.com/MCULE-1259420189/"
        }
    ]
}
api.1512517535.txt.gz · Last modified: by flack