merofoundry-client

Async Python client for the MeroFoundry public API.

MeroFoundry is a platform for building applications — data models, forms, pages and rules — and this library is the typed, httpx-based way to drive one from Python. It is the same client the merofoundry-mcp server is built on.

Install

pip install merofoundry-client

Requires Python 3.11 or newer.

Quick start

The client is asynchronous and is an async context manager, so the underlying connection pool is closed for you:

import asyncio
import os

from merofoundry_client import MeroFoundryClient

APP_ID = "..."
MODEL_ID = "..."


async def main() -> None:
    async with MeroFoundryClient(
        "https://platform.merofoundry.com",
        api_key=os.environ["MEROFOUNDRY_API_KEY"],
    ) as client:
        app = await client.get_application(APP_ID)
        print(app["name"])

        page = await client.list_records(APP_ID, MODEL_ID, per_page=50)
        print(page["total"], "records")
        for record in page["items"]:
            print(record["id"], record["data"])

        created = await client.create_record(
            APP_ID, MODEL_ID, data={"title": "Hello"}, idempotency_key="hello-1"
        )
        print(created["id"])


asyncio.run(main())

Pass the API base URL as the host root — https://platform.merofoundry.com, not a path. The client appends the public API prefix itself.

Authentication

Authentication is an API key, sent as X-API-Key. Keys are scoped to a single application and carry only the permissions granted to them, so a data-plane key that can read and write records cannot create models or delete an application. Authoring keys are considerably more powerful; treat them accordingly.

Idempotency

Writes that create something accept an idempotency_key. Passing one makes a retry safe — the same key returns the original record rather than creating a second one. Use it anywhere a network error could otherwise leave you unsure whether a write landed.

Errors

Every failure raises a subclass of MeroFoundryError, so one except clause covers the library:

from merofoundry_client import (
    MeroFoundryError,      # base class for everything below
    AuthError,             # missing or invalid key
    PermissionDeniedError, # key lacks the permission
    CapabilityError,       # the application does not offer this capability
    NotFoundError,
    ConflictError,
    ValidationError,
    StorageError,
    RateLimitError,
    ApiError,              # anything else the API returned
)

try:
    await client.get_record(APP_ID, MODEL_ID, record_id)
except NotFoundError:
    ...
except MeroFoundryError as exc:
    # exc carries the API's own code, HTTP status and message
    print(exc)

A transport failure — DNS, connection refused, timeout — also arrives as a MeroFoundryError rather than a raw httpx exception, so callers do not have to catch two families.

What it covers

41 methods across the public API:

A model must be published before records can be created against it. Adding or changing a field returns the model to draft, so re-publish after schema changes.

Status

0.1.0, pre-1.0. The API surface may still change between minor versions.