Python SDK overview

The official foodapi package is a typed HTTP client for FoodAPI. Architecture FoodAPI / AsyncFoodAPI ├── reasoning → POST /v1/reason ├── recipes →…

PythonTypeScript

ReferenceClasses Models Enums Exceptions

The official foodapi package is a typed HTTP client for FoodAPI.

Architecture

FoodAPI / AsyncFoodAPI
    ├── reasoning   → POST /v1/reason
    ├── recipes     → /v1/recipes/*
    ├── ingredients → /v1/ingredients/*
    ├── pantry      → /v1/pantry/*
    ├── developers  → portal usage (session auth)
    └── health      → GET /health

Transport (SyncTransport / AsyncTransport) handles auth headers, retries, JSON, and errors.

Public entry points

foodapi.FoodAPI ¶

FoodAPI(
    *,
    api_key: str | None = None,
    base_url: str = DEFAULT_BASE_URL,
    timeout: float = 60.0,
    max_retries: int = 3,
    user_agent: str | None = None,
    debug: bool = False,
    external_user_id: str | None = None
)

Bases: ClientDiagnosticsMixin

Official synchronous FoodAPI SDK client.

Example::

client = FoodAPI(api_key="foodapi_xxx")
result = client.reason(recipe_id="...", goal="RECOMMENDATION")
print(result.confidence_score)

debug ¶

debug() -> dict[str, Any]

Return non-secret SDK configuration for troubleshooting.

ping ¶

ping() -> dict[str, Any]

Health check with round-trip latency (uses SDK transport only).

reason ¶

reason(
    *,
    recipe_id: str | UUID,
    goal: str | ReasonGoal = RECOMMENDATION,
    pantry_item_ids: Sequence[str | UUID] | None = None,
    dietary_preferences: (
        Sequence[str | DietaryPreference] | None
    ) = None,
    max_missing_ingredients: int = 3,
    allow_substitutions: bool = True,
    include_trace: bool = False,
    external_user_id: str | None = None
) -> ReasonResponse

Convenience wrapper for client.reasoning.reason().

foodapi.AsyncFoodAPI ¶

AsyncFoodAPI(
    *,
    api_key: str | None = None,
    base_url: str = DEFAULT_BASE_URL,
    timeout: float = 60.0,
    max_retries: int = 3,
    user_agent: str | None = None,
    debug: bool = False,
    external_user_id: str | None = None
)

Bases: ClientDiagnosticsMixin

Official asynchronous FoodAPI SDK client.

Example::

async with AsyncFoodAPI(api_key="foodapi_xxx") as client:
    result = await client.reason(recipe_id="...", goal="RECOMMENDATION")

debug ¶

debug() -> dict[str, Any]

Return non-secret SDK configuration for troubleshooting.

Install

pip install foodapi

See installation, authentication, and quickstart.