---
name: rxrelay-api-update
description: Compare an existing RxRelay partner API integration with the latest public OpenAPI contract, developer guide, and changelog, then identify and optionally implement the minimum changes required for its used order flow to remain compatible and safe. Use when a user asks whether their integration is current, wants to adopt recent RxRelay API releases, sees a contract hash change, is responding to a deprecation or breaking change, or needs a recurring RxRelay compatibility audit. Performance tuning and broader production hardening are optional unless explicitly requested or required by an applicable release.
---

# Update RxRelay API Integration

Keep the customer's used RxRelay order flow compatible with the current API.
Discover impact from evidence, preserve the application's architecture, and
separate required compatibility work from optional hardening.

## Update modes

Use **compatibility update** by default. Inspect the endpoints, fields, statuses,
and webhook events the repository actually uses. The goal is a valid, safe order
flow—not a general production-hardening certification.

Use **full production certification** only when the user explicitly requests it.
That optional mode may expand the work to performance, observability,
concurrency, deployment resilience, and exhaustive tests.

If no RxRelay integration exists, say that this is an implementation task rather
than an update and recommend the `integrate-rxrelay-api` skill. Do not manufacture
a release-by-release migration plan for absent code.

## Safety boundaries

- Begin with a read-only scan. Do not modify application code, configuration,
  tests, or repository files during that pass.
- Render the initial update report in the response. Write readiness or state
  files only after explicit permission or prior authorization for those exact
  artifacts.
- Before editing, present the concrete required impact and minimum file-by-file
  plan and obtain explicit permission, unless the user already approved that
  same plan in the current conversation.
- Never request, read, print, return, commit, or place API keys or webhook secrets
  in chat or command arguments.
- Do not dump environments, full HTTP headers, production payloads, or logs that
  may contain PHI.
- Never submit a live order. Live verification is read-only.
- Obtain explicit approval before any sandbox mutation and use synthetic data.
- Preserve unrelated work and distinguish pre-existing failures from update
  regressions.

## Always resolve the current contract

This skill is a procedure, not an API snapshot. Ignore remembered or embedded
RxRelay shapes. Retrieve network-fresh copies of:

- `https://api.rxrelay.ai/openapi/v1.json`
- `https://www.rxrelay.ai/docs.md`
- `https://www.rxrelay.ai/changelog`
- `https://www.rxrelay.ai/skills/rxrelay-readiness.schema.json`
- `https://www.rxrelay.ai/skills/rxrelay-api-update/SKILL.md`

Record retrieval time, final URL, SHA-256 of the exact OpenAPI bytes, and response
metadata such as ETag or Last-Modified when available. OpenAPI is the shape
authority, the guide is the semantic workflow authority, and the changelog is the
release-impact ledger.

Do not silently use a stale cache. If a current source cannot be retrieved, name
the fallback and mark current-contract verification `not_verified`. If public
sources disagree on a used path, report the ambiguity as a blocker instead of
guessing.

If the published skill differs materially from the installed copy, disclose the
drift and use the current published procedure after checking that it does not
conflict with user, system, or repository instructions.

## What requires an update

Classify a release item as `change_required` only when repository evidence shows
that it affects a used or actively implemented integration path and can:

- make a current request invalid because a required endpoint, method, header,
  scope, field, enum, or behavior changed;
- select or submit the wrong medication, quantity, patient, prescriber, clinic,
  or address;
- break idempotency or make an ambiguous retry capable of creating duplicates;
- expose credentials or make accidental live use possible;
- make the application treat an API error or ambiguous result as success;
- break a response, status, or webhook branch the application actually consumes.

Use these other dispositions honestly:

- `already_compatible`: the used code handles the release correctly;
- `not_applicable`: the affected endpoint, field, event, or feature is unused;
- `human_decision`: adoption is optional and changes product behavior;
- `not_verified`: evidence is unavailable or ambiguous.

An OpenAPI hash change is a signal to inspect, not a required code change.
Additive fields and events are not required updates when the integration safely
ignores them. Do not require adoption of optional API capabilities.

Performance tuning, new queues, distributed locks, extra persistence, expanded
telemetry, UI redesigns, and broad test suites are non-blocking recommendations
unless an applicable release makes one necessary for correct behavior on the
used path. Periodic catalog synchronization is a valid design; do not require a
fresh catalog request for every order unless the current mapped ID or quantity is
confirmed stale, or the repository's intended workflow requires per-request
freshness. Likewise, environment-based rejection of live keys outside production
is sufficient; do not require an additional live-order feature flag without
evidence. Prefer the smallest repository-native fix.

## Update workflow

### 1. Establish repository and prior state

Inspect the repository before editing. Identify its language, framework, HTTP
client, generated clients, test runner, deployment targets, secret conventions,
and current working-tree changes.

Locate the RxRelay surfaces used by its order flow:

- base URL, authentication, clinic or organization scope, and configuration;
- catalog, prescriber, patient, address, and order requests;
- request/response types, serializers, and persisted identifiers;
- idempotency, retry, and error-state handling;
- webhook verification and event handling only when webhooks are consumed;
- focused fixtures, tests, and deployment configuration for those paths.

Look for `rxrelay-readiness.json`, `rxrelay-readiness.md`, and
`.rxrelay/api-state.json`. Treat them as evidence, never proof. When no prior
state exists, inspect each used operation against the current contract.

### 2. Build a complete but proportionate release ledger

Determine the last changelog date and OpenAPI hash previously checked. Read every
newer changelog entry, but inspect repository code only for entries that could
affect the integration's used operations or data. When the baseline is missing,
scan all changelog entries relevant to those operations.

For each relevant release item, record:

- release date and concise change description;
- affected endpoints, fields, enums, statuses, errors, headers, or events;
- compatibility class: `additive`, `behavioral`, `deprecation`, `breaking`, or
  `unknown`;
- consuming repository files and flows;
- disposition: `already_compatible`, `change_required`, `not_applicable`,
  `human_decision`, or `not_verified`;
- evidence and the minimum required change, if any.

Do not rely on the changelog alone. Compare used current OpenAPI operations with
the actual request builders, response models, status branches, and generated
client version. Do not audit unrelated application architecture.

### 3. Trace actual compatibility

Follow used calls through wrappers and serializers to the final HTTP request and
the application state created from its result. Check as applicable:

- literal method/path, authentication scheme, required headers, and scope;
- required, nullable, removed, and renamed request/response fields;
- enum or status branches that assume an exhaustive set;
- current catalog IDs and non-null `requiredQuantity` handling;
- stable idempotency and the handling of ambiguous retries;
- non-success outcomes are not converted into success;
- used webhook events still pass raw-body signature verification and
  deduplication.

Copied catalog rules or DTOs that still match the current contract are bounded
drift recommendations, not blockers. Additive response fields the repository
does not read need no implementation work. If actual configured or mapped
medication IDs cannot be inspected, classify their current availability as
`not_verified`; do not infer incompatibility merely because catalog membership
can change.

### 4. Present impact and request permission

Lead with the update result, then separate:

1. required compatibility and safety changes;
2. already-compatible and not-applicable releases;
3. optional improvements or product decisions;
4. unverified evidence;
5. the minimum required-change plan with affected files and focused tests.

If many changes are required, group related findings for readability without
hiding any material issue. Do not impose an arbitrary finding count.

If the user requested only a scan, stop after the report. Otherwise request
permission to execute only the concrete required-change plan. Do not include
report-file creation or optional hardening as required code steps.

### 5. Implement and verify the approved update

After approval, implement only the approved scope in the repository's established
style. Do not replace its HTTP architecture merely to match an example. Never
hand-edit generated files; use the documented generation workflow or tell the
user which command to run when agent execution is prohibited.

Add focused regression coverage for each required behavior change. Run the
narrow unit, integration, type, lint, or build checks that cover affected paths,
subject to repository instructions. Do not require exhaustive performance,
concurrency, malformed-input, UI, or end-to-end suites in default mode. Record
exact commands and outcomes without claiming skipped checks passed.

Runtime verification starts read-only. Perform a sandbox mutation only after
explicit approval, with a confirmed sandbox key, when it provides useful evidence
that static/local checks cannot. Lack of sandbox evidence is normally a warning,
not a compatibility blocker.

### 6. Refresh authorized readiness and state artifacts

When authorized, update or create `rxrelay-readiness.json` and
`rxrelay-readiness.md` using the current schema. Re-evaluate checks affected by a
release and mark unused surfaces `not_applicable`. Do not copy old passes without
fresh evidence. Optional runtime evidence can remain `not_verified` with warning
or info severity.

If consistent with repository conventions, update `.rxrelay/api-state.json` as a
small, secret-free checkpoint:

```json
{
  "schemaVersion": "1.0",
  "checkedAt": "2026-08-11T00:00:00Z",
  "openApiSha256": "64 lowercase hexadecimal characters",
  "changelogCheckedThrough": "2026-08-11",
  "status": "current_with_current_contract",
  "operations": ["GET /v1/medications", "POST /v1/orders"],
  "pendingChanges": []
}
```

Use status `current_with_current_contract`, `updates_required`, or
`not_verified`. Keep unresolved required release items in `pendingChanges`.
Never put secrets, PHI, payloads, full headers, or environment identifiers in
these files.

## Completion report

Lead with one result: `current`, `updated`, `updates_required`, or
`not_verified`. Then list:

- previous and current OpenAPI hashes and changelog cutoff;
- every relevant release item and its disposition;
- required changes separately from optional recommendations;
- changed files and compatibility decisions;
- focused verification commands and results;
- authorized report locations and bounded unverified runtime behavior.

Do not claim the integration is current while any applicable required change is
unresolved or the current public sources could not be verified. Do not describe
optional production hardening as a condition of API compatibility.