WallCraft-AI/api-contract.md

Cloud AI Endpoint Contract (example)

Endpoint

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

Headers

• Authorization: Bearer
• 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