Skip to main content

API versioning

Every public endpoint on this site — whether it belongs to ARC or to the ePrescription (EHR) product — carries an explicit major version in the URL path: /v1/, /v1.1/, /v2/, /v3/. That's the contract you code against — the path is stable, additive changes are safe, and breaking changes only ship as a new versioned endpoint.

What's versioned, what isn't​

Versioned:

  • URL paths — /arc/v1/authorization-requests, /ehr/v2/prescriptions, /v3/settlements, etc.
  • Request bodies (schemas evolve within a major; breaking changes trigger a new major).
  • Response bodies (same).

Not versioned (evolve freely, always additive):

  • Query parameters — new optional filters are added without notice.
  • Response headers.
  • Error error_codes — new codes can appear; existing ones are stable.

What counts as breaking​

We consider these breaking (bump the major):

  • Removing a field from a response.
  • Making an optional request field required.
  • Changing the semantics of an existing field (e.g. status: APPROVED starts meaning "partially approved").
  • Removing an enum value the API used to return.

We consider these safe (no bump):

  • Adding a new optional request field.
  • Adding a new response field.
  • Adding a new endpoint under an existing version.
  • Adding a new enum value the API used to accept from clients only. If the API starts returning a new enum value, that's breaking — bump the version.

Today's mix​

The public surface documented here currently has four versions live simultaneously across both products:

VersionWhere you'll see it
/v1/The bulk of endpoints. ARC pre-authorizations, claims, dispensing, catalogues, provider products; ePrescription v1.
/v1.1/Only POST /ehr/v1.1/prescriptions — an ePrescription variant that requires patient-data-consent validation.
/v2/Selected endpoints across both products: ARC biometric-reading v2, some ARC document-policy endpoints, medications catalogue v2, and POST /ehr/v2/prescriptions (Spain repository certification).
/v3/Settlement batches (radicaciones) — the current version of the Dominican Republic flow, under ARC.

Multiple versions of the same logical operation coexist while integrations migrate.

Deprecation contract​

When a version is superseded, we don't remove it right away. The deprecation cycle is:

  1. Deprecation header — the response starts carrying Deprecation: true and a Sunset: <date> header (RFC 8594).
  2. Docs update — the API reference marks the endpoint as deprecated with the sunset date and a pointer to the successor.
  3. Migration window — a minimum of 6 months between the deprecation announcement and the sunset date. Longer for endpoints with large-integrator adoption.
  4. Sunset — after the date, the endpoint returns 410 Gone with an error_code pointing to the successor.

If you see a Deprecation header in your logs, plan the migration ahead of the Sunset date — after that day it stops working.

Version pinning​

There is no Accept: application/vnd.osigu.v1+json style negotiation. The version is in the path — that's the whole picking mechanism. Your HTTP client just calls the URL, no version headers to configure.

  • Prescriptions — the clearest example of three versions coexisting (v1, v1.1, v2 within the ePrescription product).
  • Authorizations — currently v1 everywhere except biometric reading (v2).