{
  "openapi": "3.1.0",
  "info": {
    "title": "Medifontis API",
    "version": "1.0.0",
    "description": "Country-scoped search over official medicine sources: national regulators, ministries and agencies. Every record keeps its source, retrieval time, licence and limitations. Medifontis does not decide whether a medicine is suitable for a patient.",
    "termsOfService": "https://www.medifontis.com/us/en/terms/"
  },
  "servers": [
    {
      "url": "https://api.medifontis.com"
    }
  ],
  "externalDocs": {
    "url": "https://www.medifontis.com/us/en/docs/"
  },
  "paths": {
    "/v1/drugs": {
      "get": {
        "operationId": "searchDrugs",
        "summary": "Search medicines",
        "description": "Searches every record of every source in one country by name, active ingredient or identifier. Names match anywhere in the text; identifiers such as AIC, CN, NDC or DIN codes match from their first character. Matching ignores accents and case. Results rank exact matches first, then prefix matches, then other matches, each by record name.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z]{2}$"
            },
            "description": "Two-letter ISO 3166-1 country code, lowercase. Every search is scoped to one country."
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 120
            },
            "description": "The text to search for: a name, an active ingredient or an identifier. 3 to 120 characters, matched literally."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            },
            "description": "Number of results to return, from 1 to 50. Defaults to 20."
          },
          {
            "name": "offset",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10000,
              "default": 0
            },
            "description": "Number of results to skip, from 0 to 10000. Use the nextOffset of the previous page."
          },
          {
            "name": "kinds",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Keep only these record kinds, as comma-separated sourceId:kind pairs of the requested country, at most 12. Applied before pagination."
          },
          {
            "name": "useDomain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "human",
                "veterinary",
                "both",
                "unknown",
                "not-applicable"
              ]
            },
            "description": "Keep only records whose source classifies them for this use. human and veterinary also include products the source marks for both. Applied before pagination."
          },
          {
            "name": "species",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Keep only records with this reviewed target species, such as dog, cat, horse or cattle. Records with unknown or unmapped species are excluded. Applied before pagination."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not permit this search.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Honour the Retry-After header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable. Retry shortly; Retry-After says when.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/drugs/suggestions": {
      "get": {
        "operationId": "suggestDrugNames",
        "summary": "Suggest medicine names",
        "description": "Returns distinct names from every source for typeahead. Exact names sort first, then names starting with the query, then other matches, shorter names first. Debounce requests and ignore stale responses when the query changes.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z]{2}$"
            },
            "description": "Two-letter ISO 3166-1 country code, lowercase. Every search is scoped to one country."
          },
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 3,
              "maxLength": 120
            },
            "description": "What the user has typed so far, at least 3 characters."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 10,
              "default": 8
            },
            "description": "Number of suggestions to return, from 1 to 10. Defaults to 8."
          },
          {
            "name": "useDomain",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "human",
                "veterinary",
                "both",
                "unknown",
                "not-applicable"
              ]
            },
            "description": "Keep only records whose source classifies them for this use. human and veterinary also include products the source marks for both. Applied before pagination."
          },
          {
            "name": "species",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Keep only records with this reviewed target species, such as dog, cat, horse or cattle. Records with unknown or unmapped species are excluded. Applied before pagination."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Suggestions"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not permit this search.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Honour the Retry-After header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable. Retry shortly; Retry-After says when.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/drugs/record": {
      "get": {
        "operationId": "retrieveDrugRecord",
        "summary": "Retrieve a record",
        "description": "Reads exactly one current record by its country, source and native identity, for example to refresh a record your application saved earlier. Answers 404 when the source no longer publishes it.",
        "security": [
          {
            "bearerAuth": []
          },
          {
            "apiKeyHeader": []
          }
        ],
        "parameters": [
          {
            "name": "country",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[a-z]{2}$"
            },
            "description": "Two-letter ISO 3166-1 country code, lowercase. Every search is scoped to one country."
          },
          {
            "name": "sourceId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "The sourceId of the record, which must belong to the requested country."
          },
          {
            "name": "id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 300
            },
            "description": "The id of the record exactly as the API returned it, 1 to 300 characters."
          }
        ],
        "responses": {
          "200": {
            "description": "Success.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordResult"
                }
              }
            }
          },
          "400": {
            "description": "Invalid parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, invalid, revoked or expired API key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The key does not permit this search.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No current record with this identity.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded. Honour the Retry-After header.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable. Retry shortly; Retry-After says when.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authorization: Bearer mf_live_… Send either this header or X-Api-Key, never both."
      },
      "apiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Api-Key"
      }
    },
    "schemas": {
      "Identifier": {
        "type": "object",
        "required": [
          "scheme",
          "value"
        ],
        "properties": {
          "scheme": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      },
      "Record": {
        "type": "object",
        "required": [
          "country",
          "sourceId",
          "id",
          "kind",
          "name",
          "names",
          "identifiers",
          "data"
        ],
        "properties": {
          "country": {
            "type": "string"
          },
          "sourceId": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "names": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "identifiers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Identifier"
            }
          },
          "data": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "useDomain": {
                "type": "string",
                "enum": [
                  "human",
                  "veterinary",
                  "both",
                  "unknown",
                  "not-applicable"
                ]
              },
              "targetSpecies": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": true
                }
              }
            }
          },
          "region": {
            "type": [
              "string",
              "null"
            ]
          },
          "retrievedAt": {
            "type": "string",
            "format": "date-time"
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri"
          },
          "licence": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "id": {
                "type": "string"
              },
              "url": {
                "type": "string",
                "format": "uri"
              },
              "attribution": {
                "type": "string"
              }
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "country",
          "results",
          "nextOffset"
        ],
        "properties": {
          "country": {
            "type": "string"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Record"
            }
          },
          "nextOffset": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "Suggestions": {
        "type": "object",
        "required": [
          "country",
          "suggestions"
        ],
        "properties": {
          "country": {
            "type": "string"
          },
          "suggestions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "RecordResult": {
        "type": "object",
        "required": [
          "country",
          "record"
        ],
        "properties": {
          "country": {
            "type": "string"
          },
          "record": {
            "$ref": "#/components/schemas/Record"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}