# Connect an external app or LLM to WebCAD

Use the existing Live Project agent gateway. This is a limited, invitation-based API, not a general REST API or an MCP server. You need an HTTP-capable tool or a local script runner; reading this guide alone does not create a connection.

## Human setup

1. The human owner opens their Live Project in WebCAD and keeps it open.
2. In Live chat, under "Invite external agents", choose "Invite Architect" or "Invite Structural Engineer". Links expire after 24 hours and can be revoked by the owner.
3. Provide the invitation to the intended trusted integration through its secret configuration. Never put it in source control, public prompts or logs. The token is the value after #agent= in the original link. It is not a WebCAD user session or an AI provider key.
4. Use the APP origin from that link, followed by /api/live/agent. The showcase origin hosts documentation only. Example for the preview app: https://webcad-preview-app.web.app/api/live/agent. An app deployment with a separate API host must supply its configured gateway URL instead; ask the operator, do not guess.

## Protocol

POST JSON with Content-Type: application/json and Authorization: Agent <token>.
Do not send the token in the URL, body or any third-party request. Follow no redirects with the credential. Use HTTPS (HTTP localhost is allowed for local development).

- Read state: {"op":"state"}
  Response includes invite.role, projectName, hostOnline, context, tools, messages and commands. Context is a bounded summary, not a full model export. Tool schemas may include both disciplines: intersect them with the role allowlist below. Do not assume every advertised tool is permitted.
- Send chat only when the user requests it: {"op":"message","body":"Your message"}
  Body must contain 1–8,000 characters. Response: {"ok":true}.
- Submit a model command: {"op":"command","id":"<new UUID>","action":{"actionType":"get_model_summary"}}
  Response: {"id":"<same UUID>","status":"queued"}. This acknowledges submission, not execution or success.
- Poll {"op":"state"} every five seconds. Find the command by its id in commands. Stored statuses are pending, claimed, completed and cancelled. For completed, inspect result.success; false means the command failed. Successful commands return result.message and optionally result.data.

Architect: get_model_summary, list_levels, create_walls, create_slab.
Structural Engineer: get_model_summary, list_levels, create_columns, create_beams, create_slab.

Use the returned JSON Schema for arguments. Put arguments alongside actionType in action, not inside an arguments wrapper. Start with get_model_summary. Ask the user before modifying their model. Writes require an existing matching discipline model. Plugins installed in the app are not automatically available through this gateway.

## Failure and retry rules

The owner must keep the same Live Project open; hostOnline is a recent heartbeat, not a guarantee of successful execution. Pending commands older than five minutes are no longer eligible for execution; they may still be listed as pending. A claimed command without a result has an unknown outcome. Stop after a bounded wait and inspect state/model before retrying. Never automatically repeat a mutation with a fresh UUID. Reuse a UUID only with exactly the same action and arguments when retrying the same submission. A queued reply to a duplicate ID does not prove the previous request succeeded. State returns only the latest 30 commands for this invitation.

401: missing/malformed token, or wrong credential type for an owner-only operation.
403: expired/revoked invitation, unavailable project, rejected command or another access refusal. Ask the owner to inspect access; do not repeatedly retry.
413: request too large. Reduce the payload.
429: rate limited. Back off; do not poll faster.
503: service unavailable or not configured. Contact the deployment operator.
Network error or timeout after submission: outcome may be unknown; preserve the command ID.

## Limits and scope

This API does not invoke Caddie and does not charge WebCAD AI credits; your own LLM provider may charge separately. It cannot execute arbitrary JavaScript, manage accounts, expose every actionRegistry tool, run unattended with the owner's app closed, or provide webhooks. No public MCP endpoint, general API-key flow or versioned OpenAPI contract is offered here.

For a working, read-only Node.js 22+ example, download https://webcad-showcase.web.app/developers/examples/read-model.mjs. Set WEBCAD_AGENT_ENDPOINT and WEBCAD_AGENT_TOKEN in your local environment, then run: node read-model.mjs. It submits get_model_summary once and waits for a completed successful result. Its tests use the real HTTP handler with a simulated database response; they do not certify a particular production deployment.