> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mov-eat.app/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> High-level explanation of Moveat APIs for operations and product readers.

# API overview

Moveat APIs are not currently intended as a third-party integration product. They exist to support the web app and Agent.

This page explains API areas at a high level.

## API categories

| Category            | Prefix                 | Consumer    | Purpose                        |
| ------------------- | ---------------------- | ----------- | ------------------------------ |
| Public product APIs | `/v1`                  | Web app     | User-facing product actions.   |
| Internal Agent APIs | `/internal/v1`         | Agent       | Service-to-service operations. |
| Health APIs         | `/healthz`             | Infra       | Container and uptime checks.   |
| Swagger docs        | `/docs`, `/agent-docs` | Engineering | API inspection and debugging.  |

## Public APIs

Public APIs support web flows:

* Auth signup/login/logout.
* Google login.
* Current session/user info.
* Onboarding.
* Profile and context reads.
* Channel linking.
* Meal tracking.
* Weight tracking.
* Workout tracking.

These APIs authenticate with the user's web session.

## Internal APIs

Internal APIs support Agent flows:

* Resolve a user by linked channel.
* Fetch user context.
* Log meal entries idempotently.
* Fetch today's nutrition summary.
* Log workouts and weight entries.

These APIs authenticate with an internal service token. They should be clearly marked as Agent-only in Swagger.

## Error model

API errors should be structured and include a correlation ID when possible. This allows operations to search logs in Grafana/Loki.

Common error types:

| Status | Meaning                                                          |
| ------ | ---------------------------------------------------------------- |
| 400    | Invalid request payload.                                         |
| 401    | Missing or invalid session/token.                                |
| 403    | Authenticated but not allowed.                                   |
| 404    | Resource not found.                                              |
| 409    | Conflict, such as incomplete onboarding or idempotency conflict. |
| 429    | Rate limited.                                                    |
| 500    | Unexpected server error.                                         |

## Swagger usage

Swagger is useful for inspecting the live API contract. The business documentation should explain flows and decisions; Swagger should explain exact request and response shapes.