Worlds / Healthcare and insurance

Athenahealth API

A local athenaOne practice with departments, providers, appointment slots, patient insurance and claims. Test the scheduling and front desk agent that books, reschedules, checks eligibility and cancels visits.

Base path: /v1/{practiceid}
Auth: OAuth 2.0 client credentials bearer token, the world key
Endpoints: 18
Status: Active today

This reference previews the surface the Athenahealth world serves in the closed beta. Paths mirror the public Athenahealth API; the exact subset is confirmed when your workflow is scoped.

Connect

The run gives your agent these bindings. Keep your SDK; change only where it sends requests.

binding	meaning
`WORLDS_ATHENAHEALTH_URL`	This world's origin followed by `/v1/{practiceid}`
`WORLDS_API_KEY`	The world key, accepted wherever Athenahealth expects a credential
`WORLDS_WORLD_ID`	The isolated world's identity

js · fetch

const base = process.env.WORLDS_ATHENAHEALTH_URL + "/v1/195900";
const headers = { Authorization: "Bearer " + process.env.WORLDS_API_KEY };

const res = await fetch(base + "/appointments/open?departmentid=1&appointmenttypeid=82", {
  headers,
});

const { appointments } = await res.json();
console.log(appointments[0].appointmentid);

API reference

18 of 18

Patients

Patient demographics and contact details.

GET/v1/{practiceid}/patientsSearch patients
GET/v1/{practiceid}/patients/{patientid}Get a patient
POST/v1/{practiceid}/patientsRegister a patient
PUT/v1/{practiceid}/patients/{patientid}Update a patient

Fields · 6

`patientid`	integer	Patient id
`firstname`	string	Given name
`lastname`	string	Family name
`dob`	string	Date of birth, MM/DD/YYYY
`homephone`	string	Home phone
`departmentid`	integer	Primary department

Appointments

Open slots, bookings and cancellations.

GET/v1/{practiceid}/appointments/openList open appointment slots
GET/v1/{practiceid}/appointments/bookedList booked appointments
PUT/v1/{practiceid}/appointments/{appointmentid}Book an appointment slot
PUT/v1/{practiceid}/appointments/{appointmentid}/cancelCancel an appointment
PUT/v1/{practiceid}/appointments/{appointmentid}/checkinCheck in a patient

Fields · 6

`appointmentid`	integer	Appointment id
`appointmentstatus`	string	f (future), x (cancelled), 2 (checked in)
`date`	string	Appointment date
`starttime`	string	Start time, HH:MM
`providerid`	integer	Provider id
`appointmenttypeid`	integer	Visit type

Providers

Clinicians and their scheduling details.

GET/v1/{practiceid}/providersList providers
GET/v1/{practiceid}/providers/{providerid}Get a provider
GET/v1/{practiceid}/departmentsList departments

Fields · 5

`providerid`	integer	Provider id
`firstname`	string	Given name
`lastname`	string	Family name
`specialty`	string	Specialty
`npi`	integer	National provider id

Insurance

Insurance packages on file for a patient.

GET/v1/{practiceid}/patients/{patientid}/insurancesList patient insurances
POST/v1/{practiceid}/patients/{patientid}/insurancesAdd a patient insurance
DELETE/v1/{practiceid}/patients/{patientid}/insurances/{insuranceid}Remove a patient insurance

Fields · 5

`insuranceid`	integer	Insurance record id
`insurancepackageid`	integer	Package id
`insurancepolicyholder`	string	Policy holder
`insuranceidnumber`	string	Member id
`sequencenumber`	integer	1 primary, 2 secondary

Claims

Claims and their billing status.

GET/v1/{practiceid}/claimsList claims
GET/v1/{practiceid}/claims/{claimid}Get a claim
GET/v1/{practiceid}/patients/{patientid}/claimsList patient claims

Fields · 5

`claimid`	string	Claim id
`patientid`	integer	Patient id
`status`	string	Claim status
`servicedate`	string	Date of service
`charge`	number	Total charge

Test workflow

Prepare. Select the Athenahealth setup for your workflow and review its starting records, including patients, appointments, providers.
Connect. Configure your agent with this world's URL and key using the SDK example. Check that it reaches the intended API before running a test.
Define. Describe the task, expected final changes and records that must stay untouched. Keep expected outcomes separate from the agent's instructions.
Run and inspect. Use the dashboard or your workflow's generated CLI setup. Review final records and changes, then rerun from the same starting setup with the relevant failure conditions. Use Deployment and CI to automate the same workflow.

What to verify

No Wednesday appointments left for Dr. Sample
No two patients share a slot on Thursday
Each moved visit keeps its appointment type
Every new patient visit has an eligibility check run this week
The canceled Friday consult has a cancel reason

Test file

A task file names the jobs, the policy your agent is given and what the grader reads back from the world's final state. The agent never sees the expected outcomes.

yaml · worlds/tasks.yaml

# worlds/tasks.yaml · Athenahealth
version: 2
connector: athenahealth
seed: athenahealth-starter
mode: isolated
policy: >
  Dr. Sample is out Wednesday. Move every Wednesday visit to the next open
  slot of the same length that week, check eligibility for each new patient,
  and cancel nothing without a reason code.
tasks:
  - id: reschedule-appointments-when-a-provider-s-day-is-blocked
    prompt: "Reschedule appointments when a provider's day is blocked"
  - id: run-an-eligibility-check-before-a-new-patient-visit
    prompt: Run an eligibility check before a new patient visit
  - id: cancel-no-longer-needed-visits-with-the-right-reason
    prompt: Cancel no longer needed visits with the right reason
expected:
  - No Wednesday appointments left for Dr. Sample
  - No two patients share a slot on Thursday
  - Each moved visit keeps its appointment type
  - Every new patient visit has an eligibility check run this week
  - The canceled Friday consult has a cancel reason
scenarios:
  - slot-taken
  - token-expires
  - rate-limited

See Tasks and outcomes for every field, and Deployment and CI to run the file on every pull request.

Failure conditions

Each one fires before the handler, at the same step on every run.

condition	what the agent sees
`slot-taken`	The booking call fails because another user just booked the slot
`token-expires`	The OAuth access token returns 401 mid reschedule
`rate-limited`	Calls over the per second limit return 429
`payer-timeout`	The eligibility check comes back with no response from the payer

Starting data

Start each run from the same records and relationships. The overview below describes the Athenahealth starter; use the setup supplied for your workflow when preparing your own snapshot.

Records	Starting setup
departments	3 clinics with their own hours
providers	8, one with a blocked Wednesday
appointments	120 open slots and 70 booked across five days
patients	80 fake patients with primary insurance on file
claims	45 across draft, submitted and paid

The record shapes below reuse this world's API field definitions. They show illustrative values and placeholders, not an importable seed. API responses and seed input can differ; include all required records and references in the accepted import format for your workflow.

Patients records

Patients

Patient demographics and contact details.

Field	Type	Meaning / relationship
`patientid`	integer	Patient id
`firstname`	string	Given name
`lastname`	string	Family name
`dob`	string	Date of birth, MM/DD/YYYY
`homephone`	string	Home phone
`departmentid`	integer	Primary department

json · illustrative record shape

{
  "patientid": 1,
  "firstname": "<Given name>",
  "lastname": "<Family name>",
  "dob": "<Date of birth, MM/DD/YYYY>",
  "homephone": "<Home phone>",
  "departmentid": 1
}

See patients operations

Appointments records

Appointments

Open slots, bookings and cancellations.

Field	Type	Meaning / relationship
`appointmentid`	integer	Appointment id
`appointmentstatus`	string	f (future), x (cancelled), 2 (checked in)
`date`	string	Appointment date
`starttime`	string	Start time, HH:MM
`providerid`	integer	Provider id
`appointmenttypeid`	integer	Visit type

json · illustrative record shape

{
  "appointmentid": 1,
  "appointmentstatus": "<f (future), x (cancelled), 2 (checked in)>",
  "date": "<Appointment date>",
  "starttime": "<Start time, HH:MM>",
  "providerid": 1,
  "appointmenttypeid": 1
}

See appointments operations

Providers records

Providers

Clinicians and their scheduling details.

Field	Type	Meaning / relationship
`providerid`	integer	Provider id
`firstname`	string	Given name
`lastname`	string	Family name
`specialty`	string	Specialty
`npi`	integer	National provider id

json · illustrative record shape

{
  "providerid": 1,
  "firstname": "<Given name>",
  "lastname": "<Family name>",
  "specialty": "<Specialty>",
  "npi": 1
}

See providers operations

Insurance records

Insurance

Insurance packages on file for a patient.

Field	Type	Meaning / relationship
`insuranceid`	integer	Insurance record id
`insurancepackageid`	integer	Package id
`insurancepolicyholder`	string	Policy holder
`insuranceidnumber`	string	Member id
`sequencenumber`	integer	1 primary, 2 secondary

json · illustrative record shape

{
  "insuranceid": 1,
  "insurancepackageid": 1,
  "insurancepolicyholder": "<Policy holder>",
  "insuranceidnumber": "<Member id>",
  "sequencenumber": 1
}

See insurance operations

Claims records

Claims

Claims and their billing status.

Field	Type	Meaning / relationship
`claimid`	string	Claim id
`patientid`	integer	Patient id
`status`	string	Claim status
`servicedate`	string	Date of service
`charge`	number	Total charge

json · illustrative record shape

{
  "claimid": "<Claim id>",
  "patientid": 1,
  "status": "<Claim status>",
  "servicedate": "<Date of service>",
  "charge": 1
}

See claims operations

See the Athenahealth world in the catalog