API specs
Moveat APIs are currently internal product APIs. They are not designed as a public third-party integration surface.
This page explains what APIs exist, who consumes them and how to think about their contracts.
The exact live request and response schemas live in Platform Swagger. This page explains API ownership and behavior at a higher level for product, operations and engineering readers.
API surfaces
| Surface | Base | Consumer | Auth | Purpose |
|---|
| Platform public API | https://api.mov-eat.app/v1 | Web client | HTTP-only session cookie | User-facing product actions. |
| Platform internal API | https://api.mov-eat.app/internal/v1 | Agent | Internal service token | Service-to-service business operations. |
| Platform health | https://api.mov-eat.app/healthz | Infra | None | Container and uptime health checks. |
| Agent webhook/API | https://agent.mov-eat.app | Meta/WhatsApp and infra | Meta signature / verify token | Webhook reception and health checks. |
| Swagger public docs | https://api.mov-eat.app/docs | Engineering | Docs basic auth | Public Platform API inspection. |
| Swagger Agent docs | https://api.mov-eat.app/agent-docs | Engineering | Docs basic auth | Internal Agent API inspection. |
| Area | API responsibility |
|---|
| Auth | Signup, login, logout, Google login and session creation. |
| Me/session | Return current authenticated user/session state. |
| Onboarding | Create or update profile, goals and nutrition settings. |
| Channels | Link WhatsApp or future communication channels to the user. |
| Coaching | Store and read user coaching context. |
| Meals | Log food, read entries and nutrition summaries. |
| Weight | Log body weight, read latest weight and history. |
| Workouts | Log workout sessions, exercises and sets. |
Public API rules
- The authenticated user ID must come from the session, not from request bodies.
- Unit conversion should happen in Platform, not in the frontend.
- Public APIs should avoid leaking internal implementation details.
- Responses should be shaped for the consumer that renders them.
- Errors should include enough context to debug with logs and correlation IDs.
Internal APIs exist so Agent can delegate business actions to Platform without touching the database.
Main groups:
| Operation | Why Agent needs it |
|---|
| Resolve user by channel | Map a WhatsApp number or Telegram chat ID to a Moveat user. |
| Get user context | Fetch profile, goals, nutrition and coaching facts before generating a reply. |
| Log meal entry | Persist structured food data interpreted from a user message. |
| Get nutrition today | Answer questions like “how many calories do I have left today?”. |
| Log weight | Persist body weight sent through chat. |
| Log workout | Persist workout progress sent through chat. |
Internal API rules
- Internal APIs require the platform internal service token.
- Internal write APIs should be idempotent when triggered by webhooks.
- Agent should use source message IDs as idempotency keys whenever possible.
- Agent should not cache business facts as durable truth.
- Platform must validate the final business payload even when Agent already interpreted it.
Agent API
Agent is mostly a receiver and orchestrator. It exposes endpoints for channel providers and infrastructure.
Expected endpoints include:
| Area | Purpose |
|---|
| WhatsApp webhook verification | Handles Meta’s webhook verification challenge. |
| WhatsApp webhook events | Receives incoming user messages and delivery events. |
| Health | Allows infra to verify the service is alive. |
OpenAPI and Swagger strategy
Platform already exposes Swagger docs for live inspection. The next documentation improvement is to export the OpenAPI JSON into this docs repository so Mintlify can generate an API reference section automatically.
Recommended approach:
- Keep Swagger in Platform as the live contract source.
- Export public OpenAPI to
openapi/platform-public.json.
- Export internal Agent OpenAPI to
openapi/platform-agent.json.
- Reference both specs in
docs.json under an API Reference section.
- Keep high-level explanations in MDX pages like this one.
This keeps exact API contracts generated from code while preserving human-readable business documentation.
What should not be exposed publicly
The following should stay internal:
- Internal service token details.
- Agent-only endpoints.
- Raw infrastructure credentials.
- Database connection strings.
- Private operational dashboards.
- Any endpoint that allows cross-user access without a user session boundary.
