API Changelog

History of changes to the Midla Platform public API. Changes that could break existing integrations are always announced here before they ship.

Unreleased

HTTP errors preserve their status and headers, including 405 and Allow.
Rate limits are independent per organization, audience and token; default: 60 requests/minute.
Managing integration activation and Platform tokens requires listing and update permissions.
OpenAPI references exclude Customer endpoints from Platform specs.
Optional fields without a value must be omitted in receipt/master/house/direct creation.

Operations · Shipments: Master, House, Direct, and Consolidation now all support GET (list/show), PATCH (partial update, Draft only), and DELETE (soft delete, Draft only, 204 no content). Receipt gained DELETE. Requires shipments:delete or receipts:delete (new abilities). New read-only catalog GET /operations/shipment-movements (shipments:read) — the granular post-Confirmed operational states (dispatched, in_transit, ...), not the Draft/Confirmed/Done lifecycle.
List/show/update/create responses for receipts and shipments now include movements and documents.
Breaking: POST /direct-shipments was renamed to POST /directs, to stay consistent with the new GET/PATCH/DELETE /directs on the same resource. No transition period — same reasoning as the /api/v1 → /api/platform/v1 rename below: nobody outside this project was consuming it yet.
Breaking: explicit null is no longer accepted for optional fields on POST /masters, POST /houses, POST /directs, POST /consolidations, and POST /receipts (including packages.* sub-fields). Previously-nullable fields are now sometimes only, so they must be omitted entirely instead of sent as null — this was needed to correctly derive the new PATCH validation rules from the same source. Sending null for one of these fields now returns 422 instead of being accepted.

Operations · Masters module (new): GET/POST /masters, GET /masters/{id}, POST /masters/{id}/shipments to attach houses. Requires shipments:create/read/update.
Operations · Catalogs module: 7 new endpoints — shipment-options, places, branches, customs-offices, vessels, move-types, service-modes. Each requires its own ability. package-types now accepts a transport_mode filter.
Catalogs module: new incoterms (no ability required, same as the rest of catalogs).
Launched the Customer API — a new, separate audience (api/customer/v1/...) for a customer of your organization to query their own shipments and receipts with their own token, no scopes. It doesn't replace anything here — it's a distinct product, with its own documentation.

Breaking: the public API was renamed from /api/v1/... to /api/platform/v1/.... The segment after /api/ now identifies the calling audience, not a historical accident — it frees up the namespace for the Customer API (see above) and future audiences, unambiguously. No alias, no transition period: nobody was consuming it externally yet at that point. Any old URL using /api/v1/... must be updated to /api/platform/v1/...; everything else (auth, response format, scopes) stayed the same.

Catalogs module: added legal-forms (requires country_code), and currencies now accepts a code filter. Still requires no ability of its own.
Operations module: new catalogs package-types, commodities, and operation-types — unlike Catalogs, each requires its own ability (package-types:read, commodities:read, operation-types:read) because they're tenant-specific configuration, not global reference data.
Companies module (new): GET /companies — tenant company lookup. Requires the companies:read ability.
Users module (new): GET /users — tenant staff user lookup. Requires the users:read ability.
Helpdesk module (new): GET/POST/PATCH /tickets, GET /teams, GET /tags. Requires tickets:create/read/update, helpdesk-teams:read, or ticket-tags:read depending on the endpoint.

Catalogs module: read-only endpoints countries, states, document-types, and currencies. No ability required — a valid, active token is enough.
Partners module: GET /partners (with filters roles — required, at least one —, name, email, document_type_code + tax_id) and GET /partners/{id}. Requires the partners:read ability.