Cloud AI Endpoint Contract (example)

Endpoint
- POST https://api.youraihost.com/ai/map-prep

Headers
- Authorization: Bearer <apiToken>
- Content-Type: application/json

Request body (see data-contracts.md)
- {
  "scene": { "id": "...", "name": "..." },
  "gridSize": 32,
  "walls": [...],
  "tokens": [...],
  "promptTemplate": "...",
  "providerMetadata": { "providerName": "...", "version": "..." },
  "previewOnly": true
  }

Response
- 200 OK
  - {
      "walls": [...],
      "notes": ["Preview generated"],
      "validationHints": [...],
      "previewOnly": true
    }
- 4xx/5xx responses
  - { "error": "invalid_payload", "message": "..." }
  - { "error": "auth_failed", "message": "Invalid API token" }

Security and Privacy
- Use HTTPS; support short-lived tokens
- Minimize data; avoid sending unrelated scene data unless required
- Log access on the server side; provide per-request trace IDs