Metriport · OpenAPI Overlay 1.0.0

API Evangelist enhancements for Metriport Consolidated Patient API

4 actions 4 updates update extends openapi/metriport-patient-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for Metriport's API. It is a proposal applied on top of the contract, not a document Metriport publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-rate-limitx-conventionsx-errorsx-lifecyclex-rate-limitsx-webhooksx-error-envelopex-idempotency

Targets 4

$.info
$.paths['/medical/v1/patient'].post
$.paths['/medical/v1/patient'].get
$.paths['/medical/v1/patient/{id}'].put

OpenAPI Overlay

Raw ↑ 
overlay: 1.0.0
info:
  title: API Evangelist enhancements for Metriport Consolidated Patient API
  version: 1.0.0
  x-generated: '2026-08-14'
  x-method: generated
  x-source: 'Extends openapi/metriport-patient-api-openapi.yml with the runtime semantics Metriport documents
    in prose but does not express in a machine-readable contract: published per-operation rate limits,
    ETag concurrency, cursor pagination, the error envelope, and the retirement status of the Devices
    API operations. The original OpenAPI is never mutated.'
extends: openapi/metriport-patient-api-openapi.yml
actions:
- target: $.info
  description: Record the cross-cutting runtime semantics Metriport documents outside the spec.
  update:
    x-conventions: conventions/metriport-conventions.yml
    x-errors: errors/metriport-problem-types.yml
    x-lifecycle: lifecycle/metriport-lifecycle.yml
    x-rate-limits: rate-limits/metriport-rate-limits.yml
    x-webhooks: asyncapi/metriport-webhooks.yml
    x-error-envelope: Every failure returns {"status","name","title","detail"} as application/json. RFC
      7807-inspired, not RFC 7807 or RFC 9457 conformant. See https://docs.metriport.com/medical-api/more-info/error-responses
    x-idempotency: Not supported. Metriport documents no Idempotency-Key header; retrying a POST is not
      safe by contract. Updates use ETag/If-Match optimistic concurrency instead (412 on mismatch).
    x-rate-limit-headers: None published. No X-RateLimit-* or RateLimit-* response headers and no documented
      status code on exhaustion.
- target: $.paths['/medical/v1/patient'].post
  description: Annotate createPatient.
  update:
    x-rate-limit:
      limit: '15'
      window: minute
      rate: 1 every 4 seconds
      scope: account
      source: https://docs.metriport.com/medical-api/more-info/limits
- target: $.paths['/medical/v1/patient'].get
  description: Annotate listPatients.
  update:
    x-pagination:
      style: cursor
      params:
      - count
      - fromItem
      - toItem
      default_count: 50
      max_count: 500
      response:
      - meta.itemsOnPage
      - meta.itemsInTotal
      - meta.nextPage
      - meta.prevPage
      source: https://docs.metriport.com/medical-api/handling-data/pagination
- target: $.paths['/medical/v1/patient/{id}'].put
  description: Annotate updatePatient.
  update:
    x-rate-limit:
      limit: '15'
      window: minute
      rate: 1 every 4 seconds
      scope: account
      source: https://docs.metriport.com/medical-api/more-info/limits
    x-concurrency:
      mechanism: ETag
      request: If-Match header, or an eTag property in the body (header wins)
      conflict_status: 412
      source: https://docs.metriport.com/medical-api/more-info/etag