AveeCare Python Library

The official Python library for the AveeCare API. Read and write your home care agency's patients, visits, invoices and more from your own servers, with typed models, sync and async clients, automatic pagination, retries and idempotency built in.

• Python 3.9+, one dependency (httpx)
• Sync AveeCare and async AsyncAveeCare clients
• Typed models (py.typed), typed errors, automatic retries and idempotency keys

Install

pip install aveecare

Quickstart

Create an API key in AveeCare, then:

import os

from aveecare import AveeCare

client = AveeCare(api_key=os.environ["AVEECARE_API_KEY"])

page = client.patients.list(status="Active", limit=25)
for patient in page.data:
    print(patient.id, patient.first_name, patient.last_name)

Authentication

Every request is authenticated with your secret API key, sent as Authorization: Bearer ak_<keyId>_<secret>. Pass it as api_key, or set the AVEECARE_API_KEY environment variable and call AveeCare(). Keys are read-only or read and write; see Authentication.

Keep keys on your server. Never put an API key in browser or mobile code.

Usage

# Retrieve, create, update and delete
patient = client.patients.retrieve("pat_8f2k1m9x")
created = client.patients.create(first_name="Margaret", last_name="Alvarez")
updated = client.patients.update(created.id, scheduling_notes="Prefers morning visits", email=None)
client.patients.delete(created.id)

# Visits are listed by start-time window (at most 93 days)
visits = client.visits.list(start_from="2026-10-01T00:00:00Z", start_to="2026-10-08T00:00:00Z")

# The API key making the request
me = client.me.retrieve()

Attributes and arguments are snake_case (first_name, created_at); the library maps them to the API's camelCase JSON. On updates, passing None clears a field, and leaving an argument out leaves the field unchanged. patient.raw holds the JSON exactly as the API returned it, and patient.to_dict() converts a model back to API JSON.

Async

import asyncio

from aveecare import AsyncAveeCare


async def main() -> None:
    async with AsyncAveeCare() as client:
        page = await client.patients.list(limit=25)
        async for patient in client.patients.list(status="Active"):
            print(patient.id)


asyncio.run(main())

Pagination

list() returns the first page. Iterating the page walks every item across every page, fetching more as needed:

for patient in client.patients.list(limit=100):
    print(patient.id)

# Or one page at a time
page = client.patients.list(limit=25)
while page.has_next_page():
    page = page.get_next_page()

Errors

Every error is an AveeCareError. API errors carry status, code, type, message and request_id:

from aveecare import AveeCareError, NotFoundError

try:
    client.patients.retrieve("pat_missing")
except NotFoundError as err:
    print("No such patient", err.request_id)
except AveeCareError as err:
    print(err.status, err.code, err.message)

Network failures raise APIConnectionError, and timeouts APITimeoutError.

Retries, timeouts and idempotency

Rate-limited (429), server error (5xx) and network failures are retried twice by default with jittered exponential backoff. When the API sends Retry-After, the client waits that long.

Every create sends an Idempotency-Key (a random UUID), and the same key is reused across retries, so a retried create never makes a duplicate. Pass your own key to make a create safe to repeat across processes:

client = AveeCare(max_retries=4, timeout=20.0)

client.patients.create(
    first_name="Margaret",
    last_name="Alvarez",
    idempotency_key="import-row-1042",
    timeout=5.0,
)

Configuration

Every request sends User-Agent: aveecare-python/<version>.

Documentation

The full API reference, with every resource and field, is at www.aveecare.com/docs/api. Building an integration to offer other agencies? See the AveeCare Partner Center.

Other official SDKs

• aveecare-node: Node.js and TypeScript
• aveecare-python: Python
• aveecare-rust: Rust
• aveecare-go: Go
• aveecare-ruby: Ruby
• aveecare-php: PHP
• aveecare-java: Java and Kotlin
• aveecare-dotnet: .NET
• aveecare-cli: command line
• aveecare-openapi: OpenAPI specification
• aveecare-mcp: connect AI assistants
• aveecare-examples: sample apps

License

MIT. See LICENSE.

Built by AveeCare — home care software.