Skip to content

Reference API

In addition to this documentation Swagger and ReDoc style documentations are available.

The endpoints in this page for the long-polling version of our APIs. For streaming tokens natively, please checkout our Streaming API reference page.


Create Clinical Query

POST https://prod.askclair.ai/api/v1/clinical-query/

The "Create Clinical Query" API endpoint allows you to submit a clinical query and receive relevant information in response. When you make a POST request to the endpoint https://prod.askclair.ai/api/v1/clinical-query/, you need to include the necessary headers and payload.

Upon successful submission of the clinical query, the API will return a task_id and a ready flag with a status code of 202. This indicates that the query has been received and is being processed. If the results of the query are already cached, the API will immediately return the answer along with the corresponding references, and the status code will be 200.

By default, the API operates in question-and-answer (Q&A) mode, where it provides responses to specific clinical questions. However, if you want to receive a clinical summary instead, you can set the clinical_summary flag in the payload to true.

Please note that this endpoint is distinct from the streaming endpoint, which serves a different purpose.

import requests
token = f"token {your_token}"
url = "https://prod.askclair.ai/api/v1/clinical-query/"
headers = {'Authorization': token, 'Content-Type': 'application/json'}

payload = {
  "query": "string",
  "clinical_summary_mode": false
}

response = requests.post(url, json=payload, headers=headers)
return response.json()
const fetch = require('node-fetch');
const token = `token ${your_token}`;
const url = "https://prod.askclair.ai/api/v1/clinical-query/";

const headers = {
  'Authorization': token,
  'Content-Type': 'application/json'
};

const payload = {
  "query": "string",
  "clinical_summary_mode: false
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl 
-X POST 
-H "Authorization: token YOUR_TOKEN" 
-H "Content-Type: application/json" 
-d '{"query": "string", "clinical_summary_mode": false}' 
https://prod.askclair.ai/api/v1/clinical-query/

Make sure to replace your_token with your actual authorization token, and "string" with the actual clinical query you want to submit.

The response from the API contains four values that provide relevant information based on your clinical query. Here is an explanation of each value:

  • question: This field returns the clinical question that you asked in your API request. It helps you identify the original query for which the response is generated.

  • answer: This field returns the generated answer from the model. It provides the specific response to your clinical question, offering relevant information based on the available medical knowledge.

  • context_summary: This field returns an evidence summary based on our data. It provides a concise overview of the clinical information related to your query, highlighting key findings and insights.

  • references: This field is an array of references associated with the generated answer. Each reference object within the array contains the following information:

    • abstract: A brief summary or description of the referenced source.

    • title: The title of the referenced source.

    • link: A URL link to the referenced source, allowing you to access the full content.

    • doi: The Digital Object Identifier (DOI) associated with the referenced source, providing a unique identifier for easy retrieval.

By examining these values in the API response, you can access the generated answer, evidence summary, and relevant references to further explore and validate the information provided by the model.

Response
  {
  "question": "string",
  "answer": "string",
  "context_summary": "string",
  "references": [
    {
      "abstract": "string",
      "title": "string",
      "link": "http://example.com",
      "doi": "string"
    }
  ]
  }

Read Clinical Query

GET https://prod.askclair.ai/api/v1/clinical-query/{task_id}/

The "Read Clinical Query" endpoint allows you to check the status of a clinical query task. You can make a GET request to the endpoint https://prod.askclair.ai/api/v1/clinical-query/{task_id}/, where {task_id} represents the unique identifier of the specific task you want to check.

When you send the GET request, the API will respond with the current status of the task. If the task is complete, the response will include the answer and references fields, and the status code will be 200. This indicates that the query has finished processing, and you can retrieve the generated answer and relevant references.

However, if the task is still in progress, the API will return the task_id along with a ready flag set to false, and the status code will be 202. This signifies that the query is still being processed, and you should continue checking the status periodically.

We recommend checking the status of the task approximately every 3 seconds to stay updated on its progress. By monitoring the status using this endpoint, you can ensure timely retrieval of the answer and references once the task is complete.

import requests
headers = {
"Authorization": "token YOUR_TOKEN",
"Content-Type": "application/json"
}
url = "https://prod.askclair.ai/api/v1/clinical-query/{task_id}/"
response = requests.get(url, headers=headers)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/clinical-query/{task_id}/";
const token = `token ${your_token}`;

fetch(url,  {
headers: {
    "Authorization": `token ${token}`,
    "Content-Type": "application/json"
}
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
  curl -X GET \
  -H "Authorization: token YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  https://prod.askclair.ai/api/v1/clinical-query/{task_id}/

This response contains four values. question returns the question asked. answer returns the answer from the Model. context_summary returns the summary of the context. references returns an array of references from the model.

Response
  {
  "question": "string",
  "answer": "string",
  "context_summary": "string",
  "references": [
    {
      "abstract": "string",
      "title": "string",
      "link": "http://example.com",
      "doi": "string"
    }
  ]
  }

Create Bulk ICD10 Code Task

POST https://prod.askclair.ai/api/v1/bulk-icd-codes/

The "Create Bulk ICD10 Code Task" endpoint allows you to submit a list of up to five ICD10 codes and receive a clinical summary for all of them. To initiate the task, you need to make a POST request to the endpoint https://prod.askclair.ai/api/v1/bulk-icd-codes/.

When sending the POST request, ensure that you include the ICD10 codes in the payload of the request. The codes should be provided as a list of strings in the "codes" field.

Make sure to replace your_token with your actual authorization token. In the payload, provide the ICD10 codes of interest as elements in the "codes" list. Note that the list should not exceed five codes.

After submitting the request, the API will process the task and respond with a clinical summary for each of the ICD10 codes you provided. The response will contain the relevant information in a JSON format, which you can parse and utilize as per your application's needs.

This endpoint is particularly useful when you want to obtain a clinical summary for multiple ICD10 codes simultaneously, allowing you to gather comprehensive information for a range of medical conditions efficiently. We offer a streaming version of this endpoint (see below) if you prefer that option.

import requests
token = f"token {your_token}"
url = "https://prod.askclair.ai/api/v1/bulk-icd-codes/"
headers = {'Authorization': token, 'Content-Type': 'application/json'}

payload = {
  "codes": ["string"]
}

response = requests.post(url, json=payload, headers=headers)
return response.json()
const fetch = require('node-fetch');
const token = `token ${your_token}`;
const url = "https://prod.askclair.ai/api/v1/bulk-icd-codes/";

const headers = {
  'Authorization': token,
  'Content-Type': 'application/json'
};

const payload = {
  "codes": ["string"]
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl 
-X POST 
-H "Authorization: token YOUR_TOKEN" 
-H "Content-Type: application/json" 
-d '{"codes": ["string"]}' 
https://prod.askclair.ai/api/v1/bulk-icd-codes/

The response from the API when using the "Create Bulk ICD10 Code Task" endpoint contains two key values:

  • ready: This boolean value indicates whether the task is ready or not. If the value is false, it means that the task is still being processed and the clinical summary is not yet available. You should continue checking the status periodically until the task is marked as ready using the get bulk ICDO10 code endpoint.
  • task_id: This string value represents the unique identifier assigned to the task. You can use this task_id to retrieve the clinical summary once the task is marked as ready.

Here's an example of the response structure:

Response
  {
    "ready": false,
    "task_id": "string"
  }

Get Bulk ICD10 Code Task

GET https://prod.askclair.ai/api/v1/bulk-icd-codes/{task_id}/

The "Get Bulk ICD10 Code Task" endpoint allows you to check the status of a bulk ICD10 code task. To retrieve the status, you need to make a GET request to the endpoint https://prod.askclair.ai/api/v1/bulk-icd-codes/{task_id}/, where {task_id} represents the unique identifier of the specific task you want to check.

When you send the GET request, the API will respond with the current status of the task. You can use this endpoint to monitor the progress of the bulk ICD10 code task and determine if it has been completed or is still in progress. We recommend checking every 3 seconds.

import requests
headers = {
"Authorization": "token YOUR_TOKEN",
"Content-Type": "application/json"
}
url = "https://prod.askclair.ai/api/v1/bulk-icd-codes/{task_id}/"
response = requests.get(url)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/bulk-icd-codes/{task_id}/";

fetch(url, {
headers: {
"Authorization": `token ${token}`,
"Content-Type": "application/json"
}
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl -X GET \
-H "Authorization: token YOUR_TOKEN" \
-H "Content-Type: application/json" \ 
https://prod.askclair.ai/api/v1/bulk-icd-codes/{task_id}/

If the task is complete, a clinical summary will be returned with 200 status code. otherwise the task_id will be returned with a ready flag being false and status code 202.

Response
  {
    "codes": "string",
    "clinical_summary": "string"
  }

Create ICD10 Code Task

POST https://prod.askclair.ai/api/v1/icd-code/

The "Create ICD10 Code Task" endpoint allows you to submit an ICD10 code and create a task for it. This endpoint is designed to provide you with a clinical summary and three patient counseling points related to the specified ICD10 code. To create the task, you need to make a POST request to the endpoint https://prod.askclair.ai/api/v1/icd-code/.

When making the POST request, include the ICD10 code in the payload of the request. The code should be provided as a string in the "code" field.

import requests
token = f"token {your_token}"
url = "https://prod.askclair.ai/api/v1/icd-code/"
headers = {'Authorization': token, 'Content-Type': 'application/json'}

payload = {
  "code": "string"
}

response = requests.post(url, json=payload, headers=headers)
return response.json()
const fetch = require('node-fetch');
const token = `token ${your_token}`;
const url = "https://prod.askclair.ai/api/v1/icd-code/";

const headers = {
  'Authorization': token,
  'Content-Type': 'application/json'
};

const payload = {
  "code": "string"
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl 
-X POST 
-H "Authorization: token YOUR_TOKEN" 
-H "Content-Type: application/json" 
-d '{"code": "string"}' 
https://prod.askclair.ai/api/v1/icd-code/

The response from the API when using the "Create ICD10 Code Task" endpoint contains two key values:

  • ready: This boolean value indicates whether the task is ready or not. If the value is false, it means that the task is still being processed and the clinical summary is not yet available. You should continue checking the status periodically until the task is marked as ready using the get ICDO10 code endpoint.
  • task_id: This string value represents the unique identifier assigned to the task. You can use this task_id to retrieve the clinical summary once the task is marked as ready.

Here's an example of the response structure:

Response
  {
    "ready": false,
    "task_id": "string"
  }

Get ICD10 Code Task

GET https://prod.askclair.ai/api/v1/icd-code/{task_id}/
The "Get ICD10 Code Task" endpoint allows you to check the status of an ICD10 code task. To retrieve the status and results of the task, you need to make a GET request to the endpoint https://prod.askclair.ai/api/v1/icd-code/{task_id}/, where {task_id} represents the unique identifier of the specific task you want to check.

When you send the GET request, the API will respond with the current status of the task. If the task is complete, the API will return the clinical summary along with the patient counseling points, and the response will have a status code of 200. If the task is still in progress, the API will return the task ID with a "ready" flag set to false, and the response will have a status code of 202. We recommend checking every 3 seconds until ready.

import requests
url = "https://prod.askclair.ai/api/v1/icd-code/{task_id}/"
headers = {
      "Authorization": "token YOUR_TOKEN",
      "Content-Type": "application/json"
}
response = requests.get(url)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/icd-code/{task_id}/";

fetch(url,  {
headers: {
"Authorization": `token ${token}`,
"Content-Type": "application/json"
}
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl -X GET \
-H "Authorization: token YOUR_TOKEN" \
-H "Content-Type: application/json" \ 
https://prod.askclair.ai/api/v1/icd-code/{task_id}/

This response returns two string values. code returns the code and clinical_summary returns the summary.

Response
  {
    "code": "string",
    "clinical_summary": "string"
  }

Create Stewardship Task

POST https://prod.askclair.ai/api/v1/stewardship-query/
The "Create Stewardship Query" endpoint allows you to submit an infection, along with optional patient demographics, to obtain stewardship recommendations. Stewardship refers to the responsible and evidence-based use of antibiotics to optimize patient outcomes while minimizing the development of antibiotic resistance.

To use this endpoint, make a POST request to the following URL https://prod.askclair.ai/api/v1/stewardship-query/

Include the necessary authorization token and set the content type to JSON in the request headers. The request payload should include the infection and optional patient demographics such as age, weight, creatinine clearance (CrCl), and liver disease.

import requests
token = f"token {your_token}"
url = "https://prod.askclair.ai/api/v1/stewardship-query/"
headers = {'Authorization': token, 'Content-Type': 'application/json'}

payload = {
  "infection": "string",
  "age": 120,
  "weight": 300,
  "crcl": 200,
  "liver_disease": true
}

response = requests.post(url, json=payload, headers=headers)
return response.json()
const fetch = require('node-fetch');
const token = `token ${your_token}`;
const url = "https://prod.askclair.ai/api/v1/stewardship-query/";

const headers = {
  'Authorization': token,
  'Content-Type': 'application/json'
};

const payload = {
  "infection": "string",
  "age": 120,
  "weight": 300,
  "crcl": 200,
  "liver_disease": true
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl 
-X POST 
-H "Authorization: token YOUR_TOKEN" 
-H "Content-Type: application/json" 
-d '{"infection": "string", "age": 120, "weight": 300, "crcl": 200, "liver_disease": true}' 
https://prod.askclair.ai/api/v1/stewardship-query/

The response from the API contains two key values:

  • ready: This boolean value indicates whether the task is ready or not. If the value is false, it means that the task is still being processed and the answer is not yet available. You should continue checking the status periodically until the task is marked as ready using the read Stewardship Query endpoint.
  • task_id: This string value represents the unique identifier assigned to the task. You can use this task_id to retrieve the clinical summary once the task is marked as ready.

Here's an example of the response structure:

Response
  {
    "ready": false,
    "task_id": "string"
  }

Read Stewardship Task

GET https://prod.askclair.ai/api/v1/stewardship-query/{task_id}/
The "Read Stewardship Query" endpoint allows you to check the status and retrieve the results of a previously submitted stewardship query task. This endpoint is useful to periodically check if the task is complete and obtain the stewardship recommendations and case description.

When you send the GET request, the API will respond with the current status of the task. If the task is complete, the API will return the answer, and the response will have a status code of 200. If the task is still in progress, the API will return the task ID with a "ready" flag set to false, and the response will have a status code of 202. We recommend checking every 3 seconds until ready.

import requests
url = "https://prod.askclair.ai/api/v1/stewardship-query/{task_id}/"
headers = {
"Authorization": "token YOUR_TOKEN",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/stewardship-query/{task_id}/";

fetch(url,{
headers: {
"Authorization": `token ${token}`,
"Content-Type": "application/json"
}
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl -X GET \
-H "Authorization: token YOUR_TOKEN" \
-H "Content-Type: application/json" \ 
https://prod.askclair.ai/api/v1/stewardship-query/{task_id}/

This response returns two string values. answer returns the Stewardship recommendations and case returns the case description.

Response
  {
    "answer": "string",
    "case": "string",
    "reference": {
      "abstract": "string",
      "title": "string",
      "link": "string",
      "doi": "string"
    }
  }

Create BYOD Query Task

POST https://prod.askclair.ai/api/v1/create-byod-query-task/

The "Create BYOD Query" API endpoint allows you to submit a byod query and receive relevant information in response. When you make a POST request to the endpoint https://prod.askclair.ai/api/v1/create-byod-query-task/, you need to include the necessary headers and payload.

Upon successful submission of the byod query, the API will return a task_id and a ready flag with a status code of 202. This indicates that the query has been received and is being processed.

import requests
token = f"token {your_token}"
url = "https://prod.askclair.ai/api/v1/create-byod-query-task/"
headers = {'Authorization': token, 'Content-Type': 'application/json'}

payload = {
  "query": "string"
}

response = requests.post(url, json=payload, headers=headers)
return response.json()
const fetch = require('node-fetch');
const token = `token ${your_token}`;
const url = "https://prod.askclair.ai/api/v1/create-byod-query-task/";

const headers = {
  'Authorization': token,
  'Content-Type': 'application/json'
};

const payload = {
  "query": "string"
};

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl 
-X POST 
-H "Authorization: token YOUR_TOKEN" 
-H "Content-Type: application/json" 
-d '{"query": "string"}' 
https://prod.askclair.ai/api/v1/create-byod-query-task/

Make sure to replace your_token with your actual authorization token, and "string" with the actual clinical query you want to submit.

Here's an example of the response structure:

Response
  {
    "ready": false,
    "task_id": "string"
  }

Read BYOD Query Task

GET https://prod.askclair.ai/api/v1/get-byod-query-task/{task_id}/"
The "Read BYOD Query" endpoint allows you to check the status and retrieve the results of a previously submitted BYOD query task. This endpoint is useful to periodically check if the task is complete and obtain the answer, evidence summary, and references of a BYOD query.

When you send the GET request, the API will respond with the current status of the task. If the task is complete, the API will return the answer, and the response will have a status code of 200. If the task is still in progress, the API will return the task ID with a "ready" flag set to false, and the response will have a status code of 202. We recommend checking every 3 seconds until ready.

import requests
url = "https://prod.askclair.ai/api/v1/get-byod-query-task/{task_id}/"
headers = {
"Authorization": "token YOUR_TOKEN",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/get-byod-query-task/{task_id}/";

fetch(url,{
headers: {
"Authorization": `token ${token}`,
"Content-Type": "application/json"
}
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl -X GET \
-H "Authorization: token YOUR_TOKEN" \
-H "Content-Type: application/json" \ 
https://prod.askclair.ai/api/v1/get-byod-query-results/{task_id}/

The response from the API contains four values that provide relevant information based on your byod query. Here is an explanation of each value:

  • question: This field returns the question that you asked in your API request. It helps you identify the original query for which the response is generated.

  • answer: This field returns the generated answer from the model. It provides the specific response to your byod question, offering relevant information based what is in your documents.

  • evidence_summary: This field returns an evidence summary based on our data. It provides a concise overview of the information related to your query, in your documents, highlighting key findings and insights.

  • references: This field is an array of references associated with the generated answer. Where in your documents the answer came from. Each reference object within the array contains the following information:

    • title: The title of the referenced document.

    • confidence: A confidence score of how related the text in the document to the question asked.

    • text: The actual text in the document as is - without any AI-assisted generation or summarization.

By examining these values in the API response, you can access the generated answer, evidence summary, and relevant references to further explore and validate the information provided by the model.

Response
  {
  "question": "string",
  "answer": "string",
  "evidence_summary": "string",
  "references": [
    {
      "title": "string",
      "confidence": "95.3%",
      "text": "string"
    }
  ]
  }

Add Document to BYOD Collection

POST https://prod.askclair.ai/api/v1/add-document/

The "Add Document" endpoint allows you to use your own documents as the source of truth to Clair. By adding a document, you can later query it using the search endpoint to retrieve relevant information.

To add a document, you need to provide a minimum set of parameters, including the title and the actual document in PDF format. Optionally, you can also provide a summary, collection_name, and any unique identifiers for the document.

You can call the endpoint multiple times to upload documents in bulk. The documents will be processed via a task queue and you will be emailed when the training is complete or if there is an error.

  • title: (required) The title of the document.

  • document_url: (required or use document) the url of the pdf file.

  • document: (required or use document_url) The PDF file representing the document.

  • summary: (optional) A brief summary or abstract of the document's content.

  • collection_name: (optional) The name of the collection the document belongs to.

  • user_identifier: (optional) Any unique identifiers associated with the document.

import requests
url = "https://prod.askclair.ai/api/v1/add-document/"
headers = {
"Authorization": "token YOUR_TOKEN",
}
# if using document
files = {
'document': open('file-path/text_document.pdf', 'rb')
}
data = {
'title': 'test_document'
}
response = requests.post(url, headers=headers, files=files, data=data)
# if using document_url 
"""
data = {
  'title': 'test_document'
  'document_url': "https://example-pdf.com/test-doc.pdf"
}
response = requests.post(url, headers=headers, data=data)
"""
const fetch = require('node-fetch');
const fs = require('fs');
const url = "https://prod.askclair.ai/api/v1/add-document/";
const headers = {
'Authorization': `token ${token}`
};
// if using document_url - no need to use form
// data = {"title": "test_document", "document_url": "https://example-pdf.com/test-doc.pdf"} 
// fetch(url, {method: 'POST', headers: headers, body: JSON.stringify(data)})
const formData = new FormData();
formData.append('title', 'test_document');
formData.append('document', fs.createReadStream('file-path/text_document.pdf'));
fetch(url, {
method: 'POST',
headers: headers,
body: formData
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl --request POST 
--url https://prod.askclair.ai/api/v1/add-document/ 
--header 'Authorization: token {your token}' 
--header 'Content-Type: multipart/form-data' 
--form 'title="test_documet"' 
--form document=file-path/text_document.pdf

Here's an example of the response structure:

Response
  {
    "ready": false,
    "task_id": "string"
  }

Get All Documents

GET https://prod.askclair.ai/api/v1/get-all-documents/

The "GET ALL Documents" endpoint allows you to get the details of all the documents you previously uploaded to Clair. You can limit your query to a specific collection_name or a specific user_identifier (that you supply at the time of upload) by adding query parameters. For example, https://prod.askclair.ai/api/v1/get-all-documents/?collection_name=test?user_identifier=test-user

import requests
url = "https://prod.askclair.ai/api/v1/get-all-documents/"
headers = {
"Authorization": "token YOUR_TOKEN",
}

response = requests.get(url, headers=headers)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/get-all-documents/";
const headers = {
'Authorization': `token ${token}`
};

fetch(url, {
method: 'GET',
headers: headers,
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl --request GET 
--url https://prod.askclair.ai/api/v1/get-all-documents/ 
--header 'Authorization: token {your token}' 

Here's an example of the response structure:

Response
  {
    "documents": [
      {
        "id": 0,
        "text": "string",
        "title": "string",
        "summary": "string",
        "user_identifier": "string",
        "collection_name": "string"
      }
    ]
  }

Delete Document

DELETE https://prod.askclair.ai/api/v1/document/{document_id}

The "Delete Document" endpoint allows you to delete a document previously uploaded to Clair. You can get the document_id parameter from the Get All Documents and filtering based on your requirement.

import requests
url = "https://prod.askclair.ai/api/v1/document/{document_id}"
headers = {
"Authorization": "token YOUR_TOKEN",
}

response = requests.delete(url, headers=headers)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/document/{document_id}/";
const headers = {
'Authorization': `token ${token}`
};

fetch(url, {
method: 'DELETE',
headers: headers,
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl --request DELETE 
--url https://prod.askclair.ai/api/v1/document/{document_id} 
--header 'Authorization: token {your token}' 

If the document is deleted successfully, you will get back a 204 status code with no content. Otherwise, you will get an error response (4xx) with the error message.


Get Document Details

GET https://prod.askclair.ai/api/v1/document/{document_id}

The "GET Document" endpoint allows you to get the details of a document previously uploaded to Clair. You can get the document_id parameter from the Get All Documents and filtering based on your requirement. This endpoint is useful to display the parsed text from your document that will be used at time of query. Please note, additional text cleaning and chunking happens at the time of query to improve performance and fidelity.

import requests
url = "https://prod.askclair.ai/api/v1/document/{document_id}"
headers = {
"Authorization": "token YOUR_TOKEN",
}

response = requests.get(url, headers=headers)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/document/{document_id}/";
const headers = {
'Authorization': `token ${token}`
};

fetch(url, {
method: 'GET',
headers: headers,
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl --request GET 
--url https://prod.askclair.ai/api/v1/document/{document_id} 
--header 'Authorization: token {your token}' 

Here's an example of the response structure:

Response
  {
  "id": 0,
  "text": "string",
  "title": "string",
  "summary": "string",
  "user_identifier": "string",
  "collection_name": "string"
}

Create Drug Interaction Task

POST https://prod.askclair.ai/api/v1/create-interactions-task/
The "Create Drug Interaction Task" endpoint allows you to submit a list of drug interactions, up to 25 at a time, to get description, recommendation and references for all drug interactions present.

To use this endpoint, make a POST request to the following URL https://prod.askclair.ai/api/v1/create-interactions-task/

Include the necessary authorization token and set the content type to JSON in the request headers. The request payload should include a list of drugs. Our AI model can handle misspellings as well as non-standard drug names.

import requests
token = f"token {your_token}"
url = "https://prod.askclair.ai/api/v1/create-interactions-task/"
headers = {'Authorization': token, 'Content-Type': 'application/json'}

payload = {
  "drugs": ["string"]
}

response = requests.post(url, json=payload, headers=headers)
return response.json()
const fetch = require('node-fetch');
const token = `token ${your_token}`;
const url = "https://prod.askclair.ai/api/v1/create-interactions-task/";

const headers = {
  'Authorization': token,
  'Content-Type': 'application/json'
};

const payload = {
  "drugs": ["string"]
}

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl 
-X POST 
-H "Authorization: token YOUR_TOKEN" 
-H "Content-Type: application/json" 
-d '{"drugs": ["string"]}' 
https://prod.askclair.ai/api/v1/create-interactions-task/

The response from the API contains two key values:

  • ready: This boolean value indicates whether the task is ready or not. If the value is false, it means that the task is still being processed and the answer is not yet available. You should continue checking the status periodically until the task is marked as ready using the Get Drug Interactions Task endpoint.
  • task_id: This string value represents the unique identifier assigned to the task. You can use this task_id to retrieve drug interactions once the task is marked as ready.

Here's an example of the response structure:

Response
  {
    "ready": false,
    "task_id": "string"
  }

Get Drug Interactions Task

GET https://prod.askclair.ai/api/v1/get-interactions-task/{task_id}/
The "Get Drug Interactions Task" endpoint allows you to check the status and retrieve the results of a previously submitted drug interaction query task. This endpoint is useful to periodically check if the task is complete and obtain the drug interactions recommendationss.

When you send the GET request, the API will respond with the current status of the task. If the task is complete, the API will return the answer, and the response will have a status code of 200. If the task is still in progress, the API will return the task ID with a "ready" flag set to false, and the response will have a status code of 202. We recommend checking every 3 seconds until ready.

import requests
url = "https://prod.askclair.ai/api/v1/get-interactions-task/{task_id}/"
headers = {
"Authorization": "token YOUR_TOKEN",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/get-interactions-task/{task_id}/";

fetch(url,{
headers: {
"Authorization": `token ${token}`,
"Content-Type": "application/json"
}
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl -X GET \
-H "Authorization: token YOUR_TOKEN" \
-H "Content-Type: application/json" \ 
https://prod.askclair.ai/api/v1/get-interactions-task/{task_id}/

This response returns all drugs interactions in a list or a string of no interactions found if there are no interactions.

Response
  {
    "drug_interactions": [
      "drug_pair": "string",
      "description": "string",
      "recommendation": "string",
      "references":[
      {
        "abstract": "string",
        "title": "string",
        "link": "http://example.com",
        "doi": "string"
      }]
    ]
  }

Create Medication Review Task

POST https://prod.askclair.ai/api/v1/create-med-review-task//
The "Create Medication Review Task" endpoint allows you to submit two arrays of icd10 codes and drugs, up to 5 at a time, to get drug-related recommendation for all drugs and medical conditions present.

To use this endpoint, make a POST request to the following URL https://prod.askclair.ai/api/v1/create-med-review-task/

Include the necessary authorization token and set the content type to JSON in the request headers. The request payload should include a list of drugs and a list of icd10 codes. Our AI model can handle misspellings as well as non-standard drug names, however for dosing recommendations it needs drug strength and frequency.

import requests
token = f"token {your_token}"
url = "https://prod.askclair.ai/api/v1/create-med-review-task/"
headers = {'Authorization': token, 'Content-Type': 'application/json'}

payload = {
  "drugs": ["string"],
  "codes": ["string"], # or  "diseases": ["list of medical conditions"]
  "notes": "Any relevant notes", #optional
  "focus" : "Any therapeutic focus area" #optional
}

response = requests.post(url, json=payload, headers=headers)
return response.json()
const fetch = require('node-fetch');
const token = `token ${your_token}`;
const url = "https://prod.askclair.ai/api/v1/create-med-review-task/";

const headers = {
  'Authorization': token,
  'Content-Type': 'application/json'
};

const payload = {
  "drugs": ["string"],
  "codes": ["string"], //or "diseases": ["list of medical conditions"]
  "notes": "Any relevant notes", //optional
  "focus" : "Any therapeutic focus area" //optional
}

fetch(url, {
  method: 'POST',
  headers: headers,
  body: JSON.stringify(payload)
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl 
-X POST 
-H "Authorization: token YOUR_TOKEN" 
-H "Content-Type: application/json" 
-d '{"drugs": ["string"], "codes": ["string"]}' 
https://prod.askclair.ai/api/v1/create-med-review-task/

The response from the API contains two key values:

  • ready: This boolean value indicates whether the task is ready or not. If the value is false, it means that the task is still being processed and the answer is not yet available. You should continue checking the status periodically until the task is marked as ready using the Get Drug Interactions Task endpoint.
  • task_id: This string value represents the unique identifier assigned to the task. You can use this task_id to retrieve drug interactions once the task is marked as ready.

Here's an example of the response structure:

Response
  {
    "ready": false,
    "task_id": "string"
  }

Get Medication Review Task

GET https://prod.askclair.ai/api/v1/get-med-review-task/{task_id}/
The "Get Medication Review Task" endpoint allows you to check the status and retrieve the results of a previously submitted medication review query task. This endpoint is useful to periodically check if the task is complete and obtain the drug recommendationss.

When you send the GET request, the API will respond with the current status of the task. If the task is complete, the API will return the recommendations, and the response will have a status code of 200. If the task is still in progress, the API will return the task ID with a "ready" flag set to false, and the response will have a status code of 202. We recommend checking every 3 seconds until ready.

import requests
url = "https://prod.askclair.ai/api/v1/get-med-review-task/{task_id}/"
headers = {
"Authorization": "token YOUR_TOKEN",
"Content-Type": "application/json"
}
response = requests.get(url, headers=headers)
const fetch = require('node-fetch');
const url = "https://prod.askclair.ai/api/v1/get-med-review-task/{task_id}/";

fetch(url,{
headers: {
"Authorization": `token ${token}`,
"Content-Type": "application/json"
}
})
  .then(response => response.json())
  .then(data => {
    console.log(data);
  })
  .catch(error => {
    console.error(error);
  });
curl -X GET \
-H "Authorization: token YOUR_TOKEN" \
-H "Content-Type: application/json" \ 
https://prod.askclair.ai/api/v1/get-med-review-task/{task_id}/

This response returns Clair generated mediactions recomemndations.

Response
  {
    "recommendation": "string" 
  }