Core API
Core API info
This page describes how clients integrate with the GRENL prediction service at a contract level. It is not a full OpenAPI dump and does not document proprietary model internals, feature engineering recipes, or tuning parameters.
Base URL and versioning
- HTTP APIs are namespaced under
/api/v1(or the path your deployment mounts behind a reverse proxy). - Breaking changes bump the major version; additive fields and backward-compatible behavior stay within a version line when possible.
Format and clients
Request and response bodies are JSON with explicit schemas in the running service (Pydantic on the server). Use typed clients, validate responses in tests, and treat undocumented fields as unstable.
What the API exposes
- Health — liveness/readiness style checks suitable for orchestrators and uptime monitors.
- Reference data — stable identifiers for pricing nodes and related catalog entries your agents must agree on.
- Predictions — short-horizon signals derived from latest ISO pricing and weather inputs, returned with timestamps and model metadata so you can audit what was requested.
Exact path names, query parameters, and response shapes ship with the service; when you self-host, OpenAPI docs are typically served at /docs (Swagger UI) alongside the codebase.
Payments and access control
Deployments may enable machine-to-machine payment headers (for example HTTP 402 flows aligned with emerging conventions) when PAYMENTS_ENABLED is on. Whether metering applies to your integration depends on your contract and environment—not on this marketing page.
Errors
Clients should expect standard HTTP status codes, structured error bodies where the service provides them, and idempotent retry behavior for safe GETs. Transient upstream outages (ISO feeds, weather archives) surface as retryable failures; validation mistakes return 4xx with actionable messages—without leaking internal stack traces in production.
Stack (public)
The service is implemented as async FastAPI workers with Redis for bounded-TTL caching and TimescaleDB/Postgres for historical series—patterns chosen for latency and auditability, not novelty.
What we do not publish here
- Model architecture details, training data selection, or hyperparameter grids.
- Proprietary feature transforms, calibration procedures, or backtest methodology.
- Internal runbooks, on-call procedures, or non-public vendor terms.
Implementation access
Source, CI artifacts, and deployment definitions are shared with approved partners during technical onboarding.