The Infermedica API is available at https://api.infermedica.com/v3
. All requests to the API must be made via HTTPS (we only support TLS 1.2 and onwards).
We support cross-origin resource sharing (CORS) to allow client-side code from web applications to interact with the API. That said, you shouldn't ever expose your API credentials to any client-side code from public websites.
The Infermedica API can be easily integrated with any existing HTTP client. Our content is read-only and all of the API responses are deterministic as well as idempotent (meaning they will always return the same output for the same input, no matter how many times you call them). The API supports two HTTP methods: GET and POST.
/conditions
, and single records, e.g. /conditions/c_1
and for simple actions (e.g. /search
) that do not require any data to be sent in the request’s body./diagnosis
, /explain
or /parse
).JSON is the only data format supported by Infermedica's API. All of our endpoints return JSON objects or lists. Likewise, our POST actions expect request bodies formatted as JSON objects. Error messages are also in JSON. Requests, like responses, should be encoded in UTF-8.
Please note that we require each POST request to include the HTTP header Content-Type
with its value set to application/json
.
Infermedica API uses a custom authentication mechanism. Each of your requests must include two non-standard HTTP headers: App-Id
and App-Key
. These parameters correspond to your unique application ID and the key you create when you sign up to our Developer Portal. You can manage your credentials on the Apps page.
An example of a request could look like this (please remember to replace XXX...X
with your credentials):
curl "https://api.infermedica.com/v3/info" \
-X "GET" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
Our default medical content is focused on primary care and is available in multiple language versions. We also support custom translations and even let you create customized, domain-specific medical content. Our API organizes versions of the medical content and their corresponding translations into models.
A model represents medical content (default or custom) translated into a single language.
Our primary care medical content is currently available in over 20 languages. Content in each language is a separate model:
infermedica-ar
– Arabicinfermedica-zh
– Chinese (Simplified)infermedica-cs
– Czechinfermedica-da
– Danishinfermedica-nl
– Dutchinfermedica-en
– English model, used automatically by defaultinfermedica-et
– Estonianinfermedica-fr
– Frenchinfermedica-de
– Germaninfermedica-gr
– Greekinfermedica-it
– Italianinfermedica-es-xl
– Latin American Spanishinfermedica-pl
– Polishinfermedica-pt
– Portugueseinfermedica-pt-br
– Portuguese (Brazilian)infermedica-ro
– Romanianinfermedica-ru
– Russianinfermedica-sk
– Slovakinfermedica-es
– Spanishinfermedica-tr
– Turkishinfermedica-uk
– UkrainianPlease note that only the English model is available in the free plan. Contact us for more details.
To select a specific model you need to send its name as a custom HTTP header called Model
. Example of a request using a Ukrainian model:
curl "https://api.infermedica.com/v3/info" \
-X "GET" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Model: infermedica-uk"
We are continually working on improving our API, its underlying inference engine and its medical content. To track and document changes, we version both our API and our models. Please follow our changelog, newsletter, and blog posts to make sure you're always using the most recent versions.
Each API version is assigned its own URL. Please note that API versions are backward-incompatible. The current version of the API is available at /v3
.
We may introduce minor API changes without a URL change, so you need to make sure your implementations are flexible enough to handle them. Such changes and additions may include the following:
Our models are released independently from API updates and use a timestamp as a version indicator. You should periodically query /info
to check that the returned timestamp has the updated_at
attribute. This is especially important if you store IDs of our medical concepts (conditions, symptoms, etc.) in your application. Model updates may add, modify (or in some rare cases even delete) some of those concepts.
The /info
endpoint responds to GET requests by returning details of the selected model.
curl "https://api.infermedica.com/v3/info" \
-X "GET" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
The returned JSON object includes attributes that describe medical content, for example:
{
"updated_at": "2016-09-27T07:08:25Z",
"conditions_count": 504,
"symptoms_count": 1114,
"risk_factors_count": 41,
"lab_tests_count": 448
}
The Infermedica API offers machine learning capabilities that can improve underlying statistical models or identify interesting patterns in users’ behavior. There are two optional HTTP headers that we recommend using if you want to take advantage of these features.
Interview-Id
to group requests made during a single interview (i.e. requests made during a single conversation with a chatbot or when filling out a single intake form). Grouping requests can help to better analyze various aspects of API usage (e.g. order of questions asked, changes in condition ranking, average interview duration, or number of questions asked per interview). The Interview-Id
value should be a string and you should use the same header value for all the related requests. But please make sure you don’t use any of your users or patients’ personal data, as this violates our policies.Dev-Mode
with the value true to exclude a request from further analysis. This is useful when you make requests to the API during development of your application or when running tests; for example, all requests made through the API Reference page by default include the Dev-Mode
header.curl "https://api.infermedica.com/v3/diagnosis" \
-X "POST" \
-H "App-Id: XXXXXXXX" -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-H "Content-Type: application/json" \
-H "Interview-Id: r8oK9tf83dEtwZm9bBJU" \
-H "Dev-Mode: true" \
-d '{"sex":"male", "age":{"value": 30}, "evidence":[{"id":"s_100", "choice_id":"present"}]}'
API errors are returned using appropriate HTTP response codes and simple JSON objects with corresponding messages. Codes in the 4xx range indicate problems with your requests, while those in the 5xx range imply server-related issues (we make sure you don’t see those). For successfully completed requests, we return a 200 HTTP response code.
There are a few possible reasons for a 4xx response code:
400
- invalid JSON (e.g. extra comma), missing or invalid parameter (e.g. no age
in /diagnosis
request body)403
- missing or invalid credentials (App-Id
or App-Key
)404
- invalid URL or object not found405
- invalid HTTP method (e.g. GET instead of POST)An example of an error response accompanying response code 400
may look like this:
{ "message": "invalid json" }