Name: CompoundBrief API: ChEMBL Compound Dossiers
Brand: visionwell
SKU: api-visionwell-compoundbrief
Availability: InStock
Author: API Market

binbin7418-dotcom

# CompoundBrief Compound Dossier API

## Overview

The CompoundBrief API builds a dossier for each compound name you send. It matches the name to a ChEMBL molecule and returns its type, development phase, first approval year, formula, molecular descriptors and Lipinski rule-of-five violations, its known mechanisms of action, a summary of bioactivity records with the top targets, and the size of its literature footprint in Crossref.

It is built for pharmaceutical researchers, chemistry students, biotech analysts and drug discovery tools that need a quick overview of a list of compounds. Send up to 25 names per call. Molecule data comes from ChEMBL and is credited in every response.

## Features

*   **3 endpoints**: batch brief, single brief and health check.
*   **Molecule data**: ChEMBL ID, type, max phase, approval year, formula, SMILES and InChIKey.
*   **Descriptors**: molecular weight, ALogP, HBA, HBD, PSA and rule-of-five violations.
*   **Biology**: mechanisms of action and bioactivity counts with top targets.
*   **Literature**: number of matching works in Crossref.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **Drug discovery**: screen a list of candidate compounds.
*   **Competitive intelligence**: check development phase and mechanisms.
*   **Education**: look up a drug's properties and targets.
*   **Research tools**: enrich compound lists with ChEMBL data.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/visionwell/compoundbrief
```

### Authentication

Every request must include your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Brief a batch of compounds

Returns a dossier for each compound name and a summary.

**Method:** `POST`

**Endpoint:** `/brief/batch`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| compounds | body | Compound names, such as `aspirin` | array of strings | Yes | - | 25 |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/visionwell/compoundbrief/brief/batch' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "compounds": [
    "aspirin",
    "metformin"
  ]
}'
```

**Example Response (200 OK):**

```json
{
  "scope": "CompoundBrief joins two public sources at query time: molecule records from ChEMBL (the EMBL-EBI database of bioactive molecules) and bibliographic records from...",
  "sources": [
    "ChEMBL"
  ],
  "_attribution": "Molecule data from ChEMBL (https://www.ebi.ac.uk/chembl), the EMBL-EBI database of bioactive drug-like molecules, licensed under CC BY-SA 3.0. Bibliographic met...",
  "results": [
    {
      "query": "aspirin",
      "status": "matched",
      "errors": [],
      "molecule": {
        "chemblId": "CHEMBL25",
        "name": "ASPIRIN",
        "type": "Small molecule",
        "maxPhase": "4.0",
        "firstApproval": 1950,
        "oral": true,
        "blackBoxWarning": false,
        "formula": "C9H8O4",
        "mwFreebase": "180.16",
        "alogp": "1.31",
        "hba": 3,
        "hbd": 1,
        "psa": "63.60",
        "rtb": 2,
        "ro5Violations": 0,
        "canonicalSmiles": "CC(=O)Oc1ccccc1C(=O)O",
        "inchiKey": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
        "synonyms": [
          "8-HOUR BAYER"
        ],
        "synonymsNote": "Sample of up to 6 synonyms as listed by ChEMBL; not the full synonym set (ChEMBL lists 80+ for aspirin)."
      },
      "mechanisms": {
        "count": 1,
        "items": [
          {
            "actionType": "INHIBITOR",
            "mechanismOfAction": "Cyclooxygenase inhibitor",
            "targetId": "CHEMBL2094253",
            "diseaseEfficacy": true,
            "maxPhase": 4
          }
        ],
        "note": null
      },
      "activities": {
        "totalCount": 4087,
        "returnedCount": 50,
        "truncated": true,
        "byType": {
          "Log K'": 1,
          "Activity": 1,
          "ED25": 1,
          "IC50": 11,
          "Inhibition": 14,
          "Dose": 1,
          "ED50": 3,
          "EC50": 1,
          "Relative activity": 2,
          "ED33": 1,
          "Ratio": 1,
          "MIC": 1,
          "Absorption": 1,
          "LogD": 1,
          "Relative potency": 2,
          "Log S": 1,
          "ED30": 2,
          "LD50": 2,
          "Protection": 1,
          "No. of killed or paralyzed": 1,
          "Protected": 1
        },
        "distinctTargetsInSlice": 13,
        "topTargets": [
          {
            "targetId": "CHEMBL372",
            "targetName": "Homo sapiens",
            "organism": "Homo sapiens",
            "recordsInSlice": 11
          }
        ],
        "note": "count is the full ChEMBL total; each call returns a slice of up to 50 records, and byType / topTargets are aggregated over the returned slice only."
      },
      "literature": {
        "query": "ASPIRIN",
        "totalWorks": 33588,
        "note": "Crossref keyword search at query time: totalWorks counts works whose Crossref record matches the compound's preferred name as a keyword. It is a keyword-match c...",
        "sample": {
          "worksReturned": 10,
          "citationsInSample": 24,
          "mostCited": {
            "doi": "10.1016/s0140-6736(60)90236-1",
            "title": "SPEED OF ACTION OF ASPIRIN, SOLUBLE ASPIRIN, AND BUFFERED ASPIRIN",
            "year": 1960,
            "journal": "The Lancet",
            "citedByCount": 12
          },
          "yearRange": [
            1960
          ],
          "topJournals": [
            {
              "journal": "Aspirin and Related Drugs",
              "worksInSample": 1
            }
          ],
          "note": "The sample is Crossref's own top matches for the keyword query (10 works). Citation figures are summed over this sample only; author lists show the first 8 auth...",
          "works": [
            {
              "doi": "10.1155/2012/626289",
              "title": "Thrombosis and Aspirin: Clinical Aspect, Aspirin in Cardiology, Aspirin in Neurology, and Pharmacology of Aspirin",
              "authors": [
                "Christian Doutremepuich"
              ],
              "year": 2012,
              "type": "journal-article",
              "journal": "Thrombosis",
              "publisher": "Hindawi Limited",
              "citedByCount": 3,
              "referenceCount": 0,
              "abstract": null
            }
          ]
        }
      }
    }
  ],
  "summary": {
    "total": 2,
    "briefed": 2,
    "partial": 0,
    "matched": 2,
    "ambiguous": 0,
    "notFound": 0,
    "invalid": 0,
    "errored": 0,
    "withMechanisms": 1,
    "noMechanismRecord": 1,
    "totalActivities": 7100,
    "literatureWorksMatched": 66765
  }
}
```

#### 2. Brief one compound

Returns the dossier for one compound name.

**Method:** `POST`

**Endpoint:** `/brief/single`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| name | body | The compound name | string | Yes | - | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/visionwell/compoundbrief/brief/single' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "aspirin"
}'
```

**Example Response (200 OK):**

```json
{
  "scope": "CompoundBrief joins two public sources at query time: molecule records from ChEMBL (the EMBL-EBI database of bioactive molecules) and bibliographic records from...",
  "sources": [
    "ChEMBL",
    "Crossref"
  ],
  "_attribution": "Molecule data from ChEMBL (https://www.ebi.ac.uk/chembl), the EMBL-EBI database of bioactive drug-like molecules, licensed under CC BY-SA 3.0. Bibliographic met...",
  "brief": {
    "query": "aspirin",
    "status": "matched",
    "errors": [],
    "molecule": {
      "chemblId": "CHEMBL25",
      "name": "ASPIRIN",
      "type": "Small molecule",
      "maxPhase": "4.0",
      "firstApproval": 1950,
      "oral": true,
      "blackBoxWarning": false,
      "formula": "C9H8O4",
      "mwFreebase": "180.16",
      "alogp": "1.31",
      "hba": 3,
      "hbd": 1,
      "psa": "63.60",
      "rtb": 2,
      "ro5Violations": 0,
      "canonicalSmiles": "CC(=O)Oc1ccccc1C(=O)O",
      "inchiKey": "BSYNRYMUTXBXSQ-UHFFFAOYSA-N",
      "synonyms": [
        "8-HOUR BAYER",
        "Acetosalic Acid"
      ],
      "synonymsNote": "Sample of up to 6 synonyms as listed by ChEMBL; not the full synonym set (ChEMBL lists 80+ for aspirin)."
    },
    "mechanisms": {
      "count": 1,
      "items": [
        {
          "actionType": "INHIBITOR",
          "mechanismOfAction": "Cyclooxygenase inhibitor",
          "targetId": "CHEMBL2094253",
          "diseaseEfficacy": true,
          "maxPhase": 4
        }
      ],
      "note": null
    },
    "activities": {
      "totalCount": 4087,
      "returnedCount": 50,
      "truncated": true,
      "byType": {
        "Log K'": 1,
        "Activity": 1,
        "ED25": 1,
        "IC50": 11,
        "Inhibition": 14,
        "Dose": 1,
        "ED50": 3,
        "EC50": 1,
        "Relative activity": 2,
        "ED33": 1,
        "Ratio": 1,
        "MIC": 1,
        "Absorption": 1,
        "LogD": 1,
        "Relative potency": 2,
        "Log S": 1,
        "ED30": 2,
        "LD50": 2,
        "Protection": 1,
        "No. of killed or paralyzed": 1,
        "Protected": 1
      },
      "distinctTargetsInSlice": 13,
      "topTargets": [
        {
          "targetId": "CHEMBL372",
          "targetName": "Homo sapiens",
          "organism": "Homo sapiens",
          "recordsInSlice": 11
        },
        {
          "targetId": "CHEMBL375",
          "targetName": "Mus musculus",
          "organism": "Mus musculus",
          "recordsInSlice": 11
        }
      ],
      "note": "count is the full ChEMBL total; each call returns a slice of up to 50 records, and byType / topTargets are aggregated over the returned slice only."
    },
    "literature": {
      "query": "ASPIRIN",
      "totalWorks": 33588,
      "note": "Crossref keyword search at query time: totalWorks counts works whose Crossref record matches the compound's preferred name as a keyword. It is a keyword-match c...",
      "sample": {
        "worksReturned": 10,
        "citationsInSample": 17,
        "mostCited": {
          "doi": "10.1016/s0140-6736(60)90236-1",
          "title": "SPEED OF ACTION OF ASPIRIN, SOLUBLE ASPIRIN, AND BUFFERED ASPIRIN",
          "year": 1960,
          "journal": "The Lancet",
          "citedByCount": 12
        },
        "yearRange": [
          1960,
          2017
        ],
        "topJournals": [
          {
            "journal": "Aspirin and Related Drugs",
            "worksInSample": 1
          },
          {
            "journal": "Clinical Pharmacist",
            "worksInSample": 1
          }
        ],
        "note": "The sample is Crossref's own top matches for the keyword query (10 works). Citation figures are summed over this sample only; author lists show the first 8 auth...",
        "works": [
          {
            "doi": "10.1155/2012/626289",
            "title": "Thrombosis and Aspirin: Clinical Aspect, Aspirin in Cardiology, Aspirin in Neurology, and Pharmacology of Aspirin",
            "authors": [
              "Christian Doutremepuich"
            ],
            "year": 2012,
            "type": "journal-article",
            "journal": "Thrombosis",
            "publisher": "Hindawi Limited",
            "citedByCount": 3,
            "referenceCount": 0,
            "abstract": null
          },
          {
            "doi": "10.1186/isrctn72251782",
            "title": "Randomised study to compare aspirin versus hydroxyurea/aspirin in 'intermediate risk' primary thrombocythaemia (PT) and hydroxyurea/aspirin versus anagrelide/as...",
            "authors": [
              "AR Green"
            ],
            "year": 2012,
            "type": "dataset",
            "journal": "http://isrctn.org/&gt;",
            "publisher": "Springer Science and Business Media LLC",
            "citedByCount": 0,
            "referenceCount": 0,
            "abstract": null
          }
        ]
      }
    }
  }
}
```

#### 3. Health check

Returns the service status. It is a quick way to check that your key and the CompoundBrief service are working.

**Method:** `GET`

**Endpoint:** `/health`

**Parameters:** None.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/visionwell/compoundbrief/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "service": "CompoundBrief",
  "version": 1
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the response body holds the result. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. Check the parameter table for the endpoint. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key is valid but your subscription does not allow this request, for example an endpoint outside your plan. |
| 404 | Not Found | The path does not exist, or the resource you asked for was not found. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Slow down and retry, honouring the `Retry-After` header. |
| 500 | Internal Server Error | Something went wrong while processing the request. Retry after a short wait. |
| 503 | Service Unavailable | The service or its upstream data source is temporarily unavailable. Retry with backoff. |

## Rate Limits

Every plan allows up to 10 requests per second. Subscription plans also have a monthly call quota shown on the pricing page. Sending more than 10 requests per second returns `429 Too Many Requests`. Throttle your client to stay under 10 requests per second, back off and retry when you get a 429, and honour the `Retry-After` header when it is present.

## FAQ

*   **How are names matched?**

    By ChEMBL preferred name. Brand names and synonyms may not match, so use the generic name, such as `metformin`.

*   **Why is the bioactivity list truncated?**

    Popular compounds have thousands of records. The brief summarises a slice and gives the total count.

*   **Can I use the data commercially?**

    ChEMBL data is licensed CC BY-SA 3.0. Keep the attribution included in the response.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Brief compounds by name with ChEMBL molecule data, descriptors, mechanisms of action, bioactivity targets and literature counts.

CompoundBrief API: ChEMBL Compound Dossiers