Open API 101: a guide for clinics

New to APIs? Start here. This page explains the Shepherd Open API in everyday terms: what it is, what clinics use it for, what it can and can’t do, and who you need on your side to put it to work. No technical background needed.

You may also see it written as “OpenAPI” (one word). We mean the same thing: the Shepherd Open API.

What the Open API is

Shepherd is where your clinic’s records live. The Shepherd Open API is a secure, controlled way for other software to read and update some of those records, with your permission.

Think of it as a staff entrance to your clinic’s records that only approved software can use. That software shows a pair of keys you create, asks for one specific thing (“today’s appointments”, “invoices from last week”, “this patient’s weight history”), and gets back just that. Shepherd checks the keys on every request, and keeps each clinic’s data separate from every other clinic’s.

Two things are worth knowing up front:

It isn’t an app or a button. There’s nothing to click in Shepherd that “runs” the Open API. It’s used by software that someone writes or buys: a vendor’s product, a script your IT person builds, or a tool a developer creates with an AI coding assistant.
It works one request at a time. Software asks for a small, specific slice of data, then the next slice, and so on. That’s what makes it good at keeping two systems in step, and less suited to copying everything at once.

What clinics use it for

Most clinics that use the Open API do one of these:

Reporting and dashboards. Pull appointments, invoices, and payments into a spreadsheet, dashboard, or accounting tool on a schedule.
Keeping the schedule in step. Connect an online booking tool or reminder service so appointments show up in both places.
Client outreach. Send client contact details to a marketing or email tool you already use.
Connecting partners. Many lab, pharmacy, and specialty partners connect to Shepherd this way. If one of your vendors offers a Shepherd integration, it very likely runs on the Open API.

For more examples, see What you can build.

What data it covers

The Open API covers a lot of what your clinic does day to day, but not everything in Shepherd. Here’s the picture in plain terms.

What software can read through the Open API:

Area	What’s included
Clients	Pet owners, phone numbers and contact details, co-owners, client notes, discounts, and referral sources.
Patients	Pets, patient notes, weight history, chronic conditions, vaccine records, and files attached to the patient’s record.
Medical records	Visit (SOAP) records: history, physical exam, vitals, assessments and diagnoses, plan notes, treatments, and discharge instruction text.
Prescriptions	Prescriptions and refills.
Appointments	Appointments, appointment notes, and clinician schedules and availability.
Billing	Invoices, invoice line items, payments, and client balances.
Products and inventory	Your product and service catalog, stock levels by location, vendors, and inventory activity.
Reminders	Reminders and the notifications sent for them.
Messaging	Text conversations and messages, plus message templates.
Staff and tasks	Staff members, roles, teams, and tasks.

Some of these can also be updated through the Open API (clients, patients, appointments, tasks, and a few others), which is how booking and partner integrations keep both systems in step. Billing, inventory, and products are read-only.

What the Open API doesn’t cover today (a few examples, not a complete list):

Lab results and lab orders from your lab partners, and imaging results.
Some documents and files: visit summaries and addenda, forms and questionnaires, estimates and treatment plans, signed consent documents, and rabies certificates.
Boarding, wellness and recurring plans, whiteboard, and patient insurance details.
Change history (who changed what, and when), most clinic settings, and most of Shepherd’s built-in reports.

The Open API grows over time, so this list will shrink. For the full technical list, a developer can check the API reference.

Can I use it to keep my own backup?

It’s a fair question, and the short answer is: partly, but it isn’t a complete backup, and you may not need one.

Shepherd already backs up your data. Your practice data is backed up continuously and encrypted, and can be recovered to within minutes of any point in the last 30 days. Uploaded files such as radiographs, lab PDFs, and consent forms are kept with every earlier version preserved. The Shepherd Help Center explains it in detail: Data Backup & Recovery.

If you want a copy of your records in your own hands, there are simpler routes than the Open API:

Ask Shepherd support. A full export of your practice data is a separate process from our system backups, and support will walk you through your options. See the Help Center’s Data Backup & Recovery FAQ.
Export medical records from Shepherd. You can export a patient’s medical history (SOAP notes, lab results, and documents) as PDFs from the patient’s profile. See Exporting Medical Records.
Download reports. Many Shepherd reports can be downloaded as CSV or PDF for your own records.

If you still want an Open API copy, that’s a real software project, and it’s worth going in with clear expectations:

It will copy the parts of your records the Open API covers (see the section above), not everything in Shepherd. It’s a useful extra layer, not a replacement for an export from support.
It should be built to copy only what changed since the last run, after one careful first pass. Copying your whole history over and over is slow and uses up your request allowance.
It should run outside clinic hours, and it needs somewhere safe to keep the copy (see Keeping keys and data safe).

What you need to get started

The Open API feature on your account. It’s a paid add-on per clinic location. See Pricing & access, and ask your Shepherd account manager to turn it on.
API keys. Once the feature is on, an admin can create keys in Shepherd under Admin → Integrations. See Authentication.
Someone technical, or a vendor. Someone has to build or run the software that uses the keys. That can be:
- A vendor whose product already connects to Shepherd. Often the easiest route: they do the technical work.
- Your IT person or a local developer who builds something for you.
- A developer using an AI coding assistant. If they use a tool like Claude Code, ask them to install our free AI agent skill first. It teaches the assistant how the Shepherd Open API works and checks its work, so what it builds is correct and gentle on the system every clinic shares.
A place to test. We have a practice (“sandbox”) environment so software can be tried out without touching your live records. Ask us about it through Contact.

Questions to ask a vendor or developer

Before you hand over keys, it’s reasonable to ask:

What exactly will it read or change? Get a plain list: appointments, invoices, client contact details, and so on.
Does it copy only what changed, or does it re-download everything every time?
When does it run? Scheduled jobs belong outside clinic hours.
Where will our data be stored, and who can see it? A copy of client and patient records needs the same care as the originals.
How will you keep our keys safe? They should live in a password manager or secrets store, never in an email, a spreadsheet, or a shared document.
Have you read the Shepherd developer docs at developer.shepherd.vet? If they’re using an AI assistant, are they using the Shepherd agent skill?

Keeping keys and data safe

Treat your API keys like the keys to the clinic. Anyone holding them can reach your records through the Open API. Share them only with the person or vendor who needs them.
If a key may have leaked, ask your account manager to rotate it (replace it with a new one).
Any copy of your data outside Shepherd is yours to protect. Full medical histories and client contact details on an office computer or server need a password, restricted access, encryption, and a backup of their own.

Where to go next

Using Shepherd day to day? The Shepherd Help Center covers the app itself: reports, exports, settings, and integrations.
Ready to talk specifics? Contact us about access, keys, or a sandbox.
Handing this to a developer? Point them at the Introduction, then the API reference and the AI agent skill.