Basics

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 (opens in a new tab)) 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.

HTTP Methods

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.

• 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

JSON (opens in a new tab) 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.

Authentication

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. An Interview-Id should also be included. 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" \
  -H "Interview-Id: d083e76f-3c29-44aa-8893-587f3691c0c5"

Models

Our default medical content is focused on primary care and is available in multiple language versions. Our API organizes versions of the medical content and their corresponding translations into models.

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

• infermedica-ar – Arabic
• infermedica-zh – Chinese Simplified
• infermedica-zh-hk – Chinese Traditional (Hong Kong)
• infermedica-cs – Czech
• infermedica-nl – Dutch
• infermedica-en – English model, used automatically by default
• infermedica-et – Estonian
• infermedica-fr – French
• infermedica-de – German
• infermedica-el – Greek
• infermedica-it – Italian
• infermedica-ja – Japanese
• infermedica-es-xl – Spanish (Latin America)
• infermedica-pl – Polish
• infermedica-pt – Portuguese (Portugal)
• infermedica-pt-br – Portuguese (Brazil)
• infermedica-ro – Romanian
• infermedica-ru – Russian
• infermedica-sk – Slovak
• infermedica-es – Spanish (Spain)
• infermedica-tr – Turkish
• infermedica-uk – Ukrainian

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" \
  -H "Interview-Id: d083e76f-3c29-44aa-8893-587f3691c0c5"

Versioning

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 (opens in a new tab), and blog posts (opens in a new tab) 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 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:

• 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)

Model versions

Our models are released independently of API updates and use a timestamp as a version indicator. You should periodically query /info and check which timestamp was returned in the updated_at attribute. This is especially important if you store the IDs of our medical concepts (conditions, symptoms, etc.) in your application as model updates may add, modify, and delete concepts.

/info endpoint

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" \
  -H "Interview-Id: d083e76f-3c29-44aa-8893-587f3691c0c5"

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
}

Requests analysis

The Infermedica API offers machine learning capabilities that can improve underlying statistical models or identify interesting patterns in users’ behavior. There is one optional HTTP header that we recommend using if you want to take advantage of these features.

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 "https://api.infermedica.com/v3/diagnosis" \
  -X "POST" \
  -H "App-Id: XXXXXXXX" \
  -H "App-Key: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
  -H "Content-Type: application/json" \
  -H "Interview-Id: d083e76f-3c29-44aa-8893-587f3691c0c5" \
  -H "Dev-Mode: true" \
  -d '{"sex":"male", "age":{"value": 30}, "evidence":[{"id":"s_100", "choice_id":"present"}]}'

Errors

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.

The hardcoding of error messages is not recommended as there's no way to guarantee backward compatibility when hardcoding messages. Hardcoding in general should be used sparingly to avoid unforeseen errors, code duplication, and other maintenance issues. For instance, if the example message below is hardcoded to say "invalid json" and is later changed to "json is invalid", this will then result in an error occurring unless someone also updates the hardcoded message.

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" }