# Referência da API REST V1

Parâmetros, schemas e respostas dos endpoints IaBula V1 a partir do OpenAPI do aplicativo; acesse também Swagger e JSON.

Canonical: https://iabula.com/docs/api-reference

## Contrato legível e interativo

Esta referência extrai parâmetros e schemas do OpenAPI gerado pelo aplicativo. O Swagger continua disponível para explorar o contrato e executar chamadas autorizadas. A documentação editorial não faz chamadas de API nem requer uma chave para ser lida.

- [Abrir Swagger / FastAPI](https://iabula.com/docs/swagger)
- [Baixar OpenAPI JSON](https://iabula.com/openapi.json)

## GET /v1/medications/search

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| 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

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| 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}

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| 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 |

## POST /v1/resolve

| Campo JSON | Tipo e limites | Obrigatório |
| --- | --- | --- |
| query | string; minLength=1, maxLength=512 | yes |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | ResolveSuccess \| ResolveUnresolved |
| 400 | application/problem+json | Problem |
| 401 | application/problem+json | Problem |
| 403 | application/problem+json | Problem |
| 500 | application/problem+json | Problem |
| 503 | application/problem+json | Problem |
| 429 | application/problem+json | Problem |
| 422 | application/json | HTTPValidationError |

## GET /v1/ingredients/{id}

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| id | path | yes | string (uuid) |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | IngredientDetail |
| 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 |

## GET /v1/medications/{id}/relations

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| id | path | yes | string (uuid) |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | RelationPage |
| 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 |

## GET /v1/changes

| Parâmetro | Local | Obrigatório | Tipo e limites |
| --- | --- | --- | --- |
| since | query | no | string; maxLength=2048 \| null |
| limit | query | no | integer; minimum=1, maximum=100, default=50 |

| HTTP | Content-Type | Schema |
| --- | --- | --- |
| 200 | application/json | ChangePage |
| 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 |

## Campos do contrato OpenAPI

| Schema.campo | Tipo e limites | Obrigatório |
| --- | --- | --- |
| 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 |
| ChangeEvidence.class | string | yes |
| ChangeEvidence.source | string \| null | no |
| ChangeEvidence.dataset | string \| null | no |
| ChangeEvidence.retrieved_at | string (date-time) \| null | no |
| ChangeEvidence.source_version | string | yes |
| ChangeEvidence.source_record_id | string \| null | no |
| ChangeEvidence.source_run_id | string \| null | no |
| ChangeEvidence.attribute | string \| null | no |
| ChangeEvidence.rule_version | string \| null | no |
| ChangeEvidence.source_url | string | yes |
| ChangePage.data | array<ChangeRecord> | yes |
| ChangePage.next_cursor | string \| null | yes |
| ChangeRecord.id | string (uuid) | yes |
| ChangeRecord.entity_type | string | yes |
| ChangeRecord.entity_id | string (uuid) | yes |
| ChangeRecord.operation | string: created, updated, withdrawn, observed_in_source, changed_in_source, removed_from_source | yes |
| ChangeRecord.before | object \| null | no |
| ChangeRecord.after | object \| null | no |
| ChangeRecord.occurred_at | string (date-time) | yes |
| ChangeRecord.evidence | ChangeEvidence | yes |
| CompanyDetail.id | string (uuid) | yes |
| CompanyDetail.official_name | string | yes |
| CompanyDetail.registry_identifier | string \| null | no |
| CompanyDetail.evidence | array<Evidence> | yes |
| DCBDetail.id | string (uuid) | yes |
| DCBDetail.code | string | yes |
| DCBDetail.denomination | string | yes |
| DCBDetail.evidence | 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 |
| IngredientDetail.id | string (uuid) | yes |
| IngredientDetail.name | string | yes |
| IngredientDetail.dcbs | array<DCBDetail> | yes |
| IngredientDetail.evidence | array<Evidence> | yes |
| 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 |
| MedicationRelation.id | string (uuid) | yes |
| MedicationRelation.type | string | yes |
| MedicationRelation.source_id | string (uuid) | yes |
| MedicationRelation.target_id | string (uuid) | yes |
| MedicationRelation.direction | string | yes |
| MedicationRelation.evidence | Evidence | yes |
| MedicationRelation.valid_from | string (date) \| null | no |
| MedicationRelation.valid_to | string (date) \| null | no |
| 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 |
| RelationPage.data | array<MedicationRelation> | yes |
| ResolveRequest.query | string; minLength=1, maxLength=512 | yes |
| ResolveSuccess.status | string: resolved | yes |
| ResolveSuccess.query | string | yes |
| ResolveSuccess.resolved | ResolvedMedicationVariant | yes |
| ResolveUnresolved.status | string: unresolved | yes |
| ResolveUnresolved.query | string | yes |
| ResolveUnresolved.resolved | null | yes |
| ResolvedMedicationVariant.id | string (uuid) | yes |
| ResolvedMedicationVariant.entity_type | string: medication_variant | yes |
| ResolvedMedicationVariant.product_name | string | yes |
| ResolvedMedicationVariant.brand_name | string \| null | yes |
| ResolvedMedicationVariant.dosage_form | string | yes |
| ResolvedMedicationVariant.active_ingredient_text | string \| null | 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 |

## Recursos

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