API v3 is already available!

API v3 introduces significant improvements including enhanced reasoning algorithm, which provides better diagnostic and triage accuracy. The current version API v2 will be supported for the next six months, although the medical content updates will only be continued on v3. We recommend you to adapt your application to the v3 version.

Check the API v3 migration guidelines >>

Go to the API v3 documentation >>

Infermedica API is available at All requests to the API must be made via HTTPS (we only support TLS 1.0 and onwards).

We support cross-origin resource sharing (CORS) to allow the client-side code of web applications to interact with the API, but please make sure you never expose your API credentials in any client-side code of public websites.

HTTP Methods

Infermedica API can be easily integrated with any existing HTTP client using many popular programming languages and frameworks. Our content is read-only and all of the API responses are deterministic and 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.

  • We use GET requests to retrieve data (both lists of records, e.g./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.
  • We use POST requests for actions that require data to be sent in the request’s body (e.g. /diagnosis, /explain or /parse).


JSON is the only data format supported by Infermedica 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 created when you signed 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 "" \
  -X "GET" \


Our default medical content is focused on primary care and is available in multiple language versions. Moreover, we 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.

The model represents medical content (default or custom) translated into a single language.

Our primary care medical content is currently available in 18 languages. Content in each language is a separate model:

  • infermedica-ar – Arabic
  • infermedica-zh – Chinese (Simplified)
  • infermedica-cs – Czech
  • infermedica-nl – Dutch
  • infermedica-en – English model, used automatically by default
  • infermedica-et – Estonian
  • infermedica-fr – French
  • infermedica-de – German
  • infermedica-it – Italian
  • infermedica-pl – Polish
  • infermedica-pt – Portuguese
  • infermedica-pt-br – Portuguese (Brazilian)
  • infermedica-ro – Romanian
  • infermedica-ru – Russian
  • infermedica-sk – Slovak
  • infermedica-es – Spanish
  • infermedica-tr – Turkish
  • infermedica-uk – Ukrainian

Please 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. An example of a request using a Russian model:

curl "" \
  -X "GET" \
  -H "Model: infermedica-ru"


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.

API versions

Each API version is assigned its own URL. Please note that API versions are not backwards compatible. The current version of the API is available at /v2.

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:

  • adding new endpoints to the API
  • adding new optional query parameters to an existing endpoint
  • adding new attributes to the JSON response of an existing endpoint
  • adding new optional attributes to the JSON request of an existing endpoint
  • changing the order of attributes of JSON responses (JSON objects are by definition sets of unordered key/value pairs)

Version /v1 is no longer supported and you should switch to /v2 as soon as possible. Please also note that we are already working on /v3. Feel free to contact us if you have any suggestions or feature requests. We will be releasing a /v3 preview shortly.

Model versions

Our models are released independently from API updates and use a timestamp as a version indicator. You should periodically query /info endpoint to check the timestamp returned as the updated_at attribute. This is especially important if you store the 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.

/info endpoint

The /info endpoint responds to GET requests by returning details of the selected model.

curl "" \
  -X "GET" \

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

Requests analysis

Infermedica API offers machine learning capabilities that can help to 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 all features offered by Infermedica.

  • Use the HTTP header 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 the number of questions asked per interview). The Interview-Id value should be a string and you should use the same header value for all related requests. But please make sure you don’t use any of your users or patients’ personal data, as this violates our policies.
  • Use the HTTP header 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 "" \
  -X "POST" \
  -H "Content-Type: application/json" \
  -H "Interview-Id: r8oK9tf83dEtwZm9bBJU" \
  -H "Dev-Mode: true" \
  -d '{"sex":"male", "age":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 found
  • 405 - 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" }