Skip to main content

​
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

​
Platform public API

Platform public APIs support the web app. They should be stable, user-oriented and safe to call from the browser. Main groups:

​
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.

​
Platform internal API for Agent

Internal APIs exist so Agent can delegate business actions to Platform without touching the database. Main groups:

​
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: Agent should keep channel-specific code inside channel adapters. Business logic should live in orchestration and should call Platform for durable actions.

​
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:
  1. Keep Swagger in Platform as the live contract source.
  2. Export public OpenAPI to openapi/platform-public.json.
  3. Export internal Agent OpenAPI to openapi/platform-agent.json.
  4. Reference both specs in docs.json under an API Reference section.
  5. 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.