# Medication search and canonical records

Search Brazilian medications by name, filter records and retrieve canonical details with cursor pagination and evidence.

Canonical: https://iabula.com/docs/en/medications

## Name search and filters

GET /v1/medications/search matches a literal substring of the official name, case-insensitively. Search returns a list of records; it does not declare that the query identifies one unique variant. %, _ and ! are not wildcards.

```bash
curl --fail-with-body --get "$IABULA_API_BASE/v1/medications/search" \
  --header "X-API-Key: $IABULA_API_KEY" \
  --data-urlencode 'q=dipirona' \
  --data-urlencode 'limit=20'
```

When provided, q accepts 1–256 characters. limit accepts 1–100, default 20. ingredient_id and category_id are canonical UUIDs. dosage_form matches the canonical dosage form case-insensitively. Filters depend on links actually present in the catalog.

## Stable cursor pagination

Each page contains data and next_cursor. Pass the returned cursor without decoding or modifying it. Search cursors are bound to the filters; restart without a cursor when changing q or another filter. Invalid or mismatched cursors return HTTP 400.

```bash
curl --fail-with-body --get "$IABULA_API_BASE/v1/medications/search" \
  --header "X-API-Key: $IABULA_API_KEY" \
  --data-urlencode "q=dipirona" \
  --data-urlencode "cursor=$IABULA_CURSOR"
```

## Exact identifier lookup

GET /v1/medications/lookup accepts EAN, CMED_GGREM or CMED_REGISTRO and a literal value. matched identifies one candidate; ambiguous retains separate candidates; unresolved does not invent a name match. Each candidate includes reusable IDs and source evidence.

```bash
curl --fail-with-body --get "$IABULA_API_BASE/v1/medications/lookup"   --header "X-API-Key: $IABULA_API_KEY"   --data-urlencode "scheme=EAN"   --data-urlencode "value=7891058021580"
```

## Details using a returned UUID

Use an id returned by search in GET /v1/medications/{id}. Details include product_id and lists of presentations, registrations, companies and categories when available. Do not invent UUIDs or derive an ID from a name. Unknown IDs return HTTP 404.

```bash
curl --fail-with-body "$IABULA_API_BASE/v1/medications/$IABULA_MEDICATION_ID" \
  --header "X-API-Key: $IABULA_API_KEY"
```

## Interpret fields with evidence

product_name, brand_name, dosage_form and active_ingredient_text have distinct meanings. Unmapped fields may be null. active_ingredient_text preserves source text and does not prove a link to ActiveIngredient. Regulatory categories are not clinical indications.

- [Provenance](https://iabula.com/docs/en/provenance)
- [Search versus Resolve](https://iabula.com/docs/en/resolve)
- [Name search guide](https://iabula.com/docs/en/guides/buscar-medicamento-por-nome)

## GET /v1/medications/search

| Parameter | Location | Required | Type and bounds |
| --- | --- | --- | --- |
| q | query | no | string; minLength=1, maxLength=256 \| null |
| ingredient_id | query | no | string (uuid) \| null |
| dosage_form | query | no | string; minLength=1, maxLength=100 \| null |
| category_id | query | no | string (uuid) \| null |
| identifier_scheme | query | no | string: EAN, CMED_GGREM, CMED_REGISTRO \| null |
| identifier_value | query | no | string; minLength=1, maxLength=64 \| null |
| expand | query | no | string: catalog_context \| null |
| limit | query | no | integer; minimum=1, maximum=100, default=20 |
| cursor | query | no | string; maxLength=2048 \| null |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | MedicationPage |
| 400 | application/json | Problem |
| 401 | application/json | Problem |
| 403 | application/json | Problem |
| 429 | application/json | Problem |
| 500 | application/json | Problem |
| 503 | application/json | Problem |
| 422 | application/json | HTTPValidationError |

## GET /v1/medications/lookup

| Parameter | Location | Required | Type and bounds |
| --- | --- | --- | --- |
| scheme | query | yes | string: EAN, CMED_GGREM, CMED_REGISTRO |
| value | query | yes | string; minLength=1, maxLength=64 |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | IdentifierLookup |
| 400 | application/json | Problem |
| 401 | application/json | Problem |
| 403 | application/json | Problem |
| 429 | application/json | Problem |
| 500 | application/json | Problem |
| 503 | application/json | Problem |
| 422 | application/json | HTTPValidationError |

## GET /v1/medications/{id}

| Parameter | Location | Required | Type and bounds |
| --- | --- | --- | --- |
| id | path | yes | string (uuid) |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | MedicationDetail |
| 400 | application/json | Problem |
| 401 | application/json | Problem |
| 403 | application/json | Problem |
| 429 | application/json | Problem |
| 500 | application/json | Problem |
| 503 | application/json | Problem |
| 404 | application/json | Problem |
| 422 | application/json | HTTPValidationError |

## OpenAPI contract fields

| Schema.field | Type and bounds | Required |
| --- | --- | --- |
| CatalogContext.source_substances | array<SupportedSourceValue> | yes |
| CatalogContext.source_laboratories | array<SupportedSourceValue> | yes |
| CatalogContext.source_identifiers | array<SupportedSourceIdentifier> | yes |
| CatalogContext.variants | array<CatalogVariant> | yes |
| CatalogIngredient.id | string (uuid) | yes |
| CatalogIngredient.name | string | yes |
| CatalogIngredient.role | string \| null | no |
| CatalogIngredient.amount_text | string \| null | no |
| CatalogIngredient.evidence | array<Evidence> | yes |
| CatalogPresentation.id | string (uuid) | yes |
| CatalogPresentation.strength | string \| null | no |
| CatalogPresentation.unit_count | integer \| null | no |
| CatalogPresentation.package_description | string \| null | no |
| CatalogPresentation.identifiers | array<SupportedSourceIdentifier> | yes |
| CatalogPresentation.evidence | array<Evidence> | yes |
| CatalogPreview.source_substances | array<string> | yes |
| CatalogPreview.source_laboratories | array<string> | yes |
| CatalogPreview.cmed_registrations | array<string> | yes |
| CatalogPreview.has_multiple_source_values | boolean | yes |
| CatalogPreview.source_values_truncated | boolean | yes |
| CatalogPreview.presentation_count | integer | yes |
| CatalogPreview.presentations | array<CatalogPreviewPresentation> | yes |
| CatalogPreviewPresentation.id | string (uuid) | yes |
| CatalogPreviewPresentation.variant_id | string (uuid) | yes |
| CatalogPreviewPresentation.dosage_form | string \| null | no |
| CatalogPreviewPresentation.strength | string \| null | no |
| CatalogPreviewPresentation.unit_count | integer \| null | no |
| CatalogPreviewPresentation.package_description | string \| null | no |
| CatalogPreviewPresentation.ggrem | array<string> | yes |
| CatalogPreviewPresentation.eans | array<string> | yes |
| CatalogPreviewPresentation.matches_identifier | boolean | yes |
| CatalogVariant.id | string (uuid) | yes |
| CatalogVariant.dosage_form | string \| null | no |
| CatalogVariant.evidence | array<Evidence> | yes |
| CatalogVariant.ingredients | array<CatalogIngredient> | yes |
| CatalogVariant.presentations | array<CatalogPresentation> | yes |
| CategoryDetail.id | string (uuid) | yes |
| CategoryDetail.vocabulary_name | string | yes |
| CategoryDetail.code | string \| null | no |
| CategoryDetail.name | string | yes |
| CategoryDetail.evidence | array<Evidence> | yes |
| CompanyDetail.id | string (uuid) | yes |
| CompanyDetail.official_name | string | yes |
| CompanyDetail.registry_identifier | string \| null | no |
| CompanyDetail.evidence | array<Evidence> | yes |
| Evidence.class | string | yes |
| Evidence.source | string \| null | no |
| Evidence.dataset | string \| null | no |
| Evidence.retrieved_at | string (date-time) \| null | no |
| Evidence.source_version | string \| null | no |
| Evidence.source_record_id | string \| null | no |
| Evidence.source_run_id | string \| null | no |
| Evidence.attribute | string \| null | no |
| Evidence.rule_version | string \| null | no |
| HTTPValidationError.detail | array<ValidationError> | no |
| IdentifierCandidate.product_id | string (uuid) | yes |
| IdentifierCandidate.product_name | string | yes |
| IdentifierCandidate.variant_id | string (uuid) \| null | no |
| IdentifierCandidate.dosage_form | string \| null | no |
| IdentifierCandidate.presentation_id | string (uuid) \| null | no |
| IdentifierCandidate.strength | string \| null | no |
| IdentifierCandidate.package_description | string \| null | no |
| IdentifierCandidate.evidence | array<Evidence> | yes |
| IdentifierLookup.status | string: matched, ambiguous, unresolved | yes |
| IdentifierLookup.scheme | string: EAN, CMED_GGREM, CMED_REGISTRO | yes |
| IdentifierLookup.value | string | yes |
| IdentifierLookup.candidates | array<IdentifierCandidate> | yes |
| IdentifierLookup.reason | string: no_exact_match, multiple_exact_matches \| null | no |
| MedicationDetail.id | string (uuid) | yes |
| MedicationDetail.product_name | string | yes |
| MedicationDetail.brand_name | string \| null | no |
| MedicationDetail.dosage_form | string \| null | no |
| MedicationDetail.active_ingredient_text | string \| null | no |
| MedicationDetail.evidence | array<Evidence> | yes |
| MedicationDetail.catalog_context | CatalogContext \| null | no |
| MedicationDetail.identity_preview | CatalogPreview \| null | no |
| MedicationDetail.product_id | string (uuid) | yes |
| MedicationDetail.presentations | array<PresentationDetail> | yes |
| MedicationDetail.registrations | array<RegistrationDetail> | yes |
| MedicationDetail.companies | array<CompanyDetail> | yes |
| MedicationDetail.categories | array<CategoryDetail> | yes |
| MedicationPage.data | array<MedicationSummary> | yes |
| MedicationPage.next_cursor | string \| null | yes |
| MedicationSummary.id | string (uuid) | yes |
| MedicationSummary.product_name | string | yes |
| MedicationSummary.brand_name | string \| null | no |
| MedicationSummary.dosage_form | string \| null | no |
| MedicationSummary.active_ingredient_text | string \| null | no |
| MedicationSummary.evidence | array<Evidence> | yes |
| MedicationSummary.catalog_context | CatalogContext \| null | no |
| MedicationSummary.identity_preview | CatalogPreview \| null | no |
| PresentationDetail.id | string (uuid) | yes |
| PresentationDetail.strength | string \| null | no |
| PresentationDetail.package_description | string \| null | no |
| PresentationDetail.evidence | array<Evidence> | yes |
| Problem.type | string | yes |
| Problem.title | string | yes |
| Problem.status | integer | yes |
| Problem.code | string | yes |
| Problem.detail | string \| null | no |
| Problem.request_id | string | yes |
| RegistrationDetail.id | string (uuid) | yes |
| RegistrationDetail.authority | string | yes |
| RegistrationDetail.registration_number | string | yes |
| RegistrationDetail.status | string \| null | no |
| RegistrationDetail.valid_from | string (date) \| null | no |
| RegistrationDetail.valid_to | string (date) \| null | no |
| RegistrationDetail.valid_to_month | string \| null | no |
| RegistrationDetail.evidence | array<Evidence> | yes |
| SupportedSourceIdentifier.value | string | yes |
| SupportedSourceIdentifier.evidence | array<Evidence> | yes |
| SupportedSourceIdentifier.scheme | string: CMED_REGISTRO, CMED_CNPJ, CMED_GGREM, EAN | yes |
| SupportedSourceValue.value | string | yes |
| SupportedSourceValue.evidence | array<Evidence> | yes |
| ValidationError.loc | array<string \| integer> | yes |
| ValidationError.msg | string | yes |
| ValidationError.type | string | yes |
| ValidationError.input | object | no |
| ValidationError.ctx | object | no |

## Resources

- [OpenAPI JSON](https://iabula.com/openapi.json)
- [Swagger](https://iabula.com/docs/swagger)
- [Documentation index](https://iabula.com/llms.txt)