API & PLUGINS

Your tools.
Your AI.
Connected to WebCAD.

Build a model-checking plugin or connect your own app to a Live Project. Start with a working example and instructions you can give your LLM.

Build a plugin Connect an app

Package SDK v1 · Invitation-based Live API · Contract checked 15 October 2026

START HERE

What works today

Available

Plugins inside WebCAD

Read and update model data through a scoped SDK. Validate, preview, install and share versioned JSON packages. Installed commands are available to Caddie.

Limited API

External apps & agents

Use an invitation to read project context, chat and submit allowed discipline commands. The owner must keep the Live Project open to execute commands.

Not available

Unattended integrations

No public MCP endpoint, general API keys, webhooks or full REST/OpenAPI contract. The Live API does not expose every WebCAD or plugin command.

01 / INSIDE WEBCAD

Build a plugin

A plugin is a .webcad-plugin.json file containing metadata, permissions and JavaScript command bodies. No separate build toolchain is needed for this example.

Give your LLM the same guide as Plugin Studio

Copy the full package contract, asynchronous SDK reference and example. Add a sentence describing what your plugin should do.

Open plain-text guide ↗

Get the example. Download Wall Counter. It counts IfcWall elements and only requests elements:read.
Import it. Open Plugins in WebCAD, then choose Import package in Plugin Studio. Inspect the source and permissions in Build.
Run a preview. Select Count walls, use {} as parameters, and choose Preview. The returned value contains wallCount; an empty model returns zero. This query does not change the model.
Make it yours. Ask your LLM for a new package ID, your author details and the smallest necessary permissions. Validate and preview before installing; review before publishing to the shared library.

Inspect the complete Wall Counter package

Download the JSON example using the link above.

SDK boundaries

Await every SDK call. Use the provided model, selection, project, storage and notice/export methods. Commands have a 15-second deadline and a 1,000-effect limit. Package v1 has no direct network, DOM, filesystem, persistent event subscriptions or custom modal UI. Legacy local scripts use a different trusted runtime; use Package v1 for new shared plugins.

02 / OUTSIDE WEBCAD

Connect an app or AI agent

Your integration calls the Live Project gateway over HTTP. It runs its own logic or LLM; these requests do not invoke Caddie or consume WebCAD AI credits. Your LLM provider may charge separately.

A connection guide your LLM can read

Includes authentication, allowed commands, polling and failure handling. Your LLM needs an HTTP tool or script runner to use it.

Open plain-text guide ↗

Create an invitation. As the Live Project owner, open Live chat → Invite external agents → Invite Architect or Invite Structural Engineer.
Configure your integration locally. Take the token after #agent= in the original invitation link. Keep it in secret configuration. Set the endpoint to the app's origin plus /api/live/agent, not this showcase website. For a separate API deployment, ask its operator for the gateway URL.
Keep the project open. Invitations expire after 24 hours and can be revoked. Writes also require a matching discipline model. The external agent needs no separate WebCAD account.
Run the read-only example. Download read-model.mjs, configure the two environment variables below, and run with Node.js 22+. It requests the model summary once and polls every five seconds until a result arrives or the bounded wait ends.

Bash / macOS / Linux · Enter your token locally at the prompt; never paste it into this website.

export WEBCAD_AGENT_ENDPOINT='https://webcad-preview-app.web.app/api/live/agent'
read -r -s -p 'Agent token: ' WEBCAD_AGENT_TOKEN; echo
export WEBCAD_AGENT_TOKEN
node read-model.mjs

Windows PowerShell setup

$env:WEBCAD_AGENT_ENDPOINT = 'https://webcad-preview-app.web.app/api/live/agent'
$agentSecret = Read-Host 'Agent token' -AsSecureString
$env:WEBCAD_AGENT_TOKEN = [System.Net.NetworkCredential]::new('', $agentSecret).Password
node read-model.mjs

Use your invitation's app origin if it differs from this preview deployment.

Inspect the Node.js example

Download read-model.mjs using the link above.

Check the connection with curl

After setting the same environment variables in Bash, this returns state without submitting a model command:

curl --fail-with-body --silent --show-error --max-time 20 \
  "$WEBCAD_AGENT_ENDPOINT" \
  -H "Authorization: Agent $WEBCAD_AGENT_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"op":"state"}'

Tokens stay with your integration

An invitation grants project access. Share it only with the intended trusted integration; keep it out of source control, logs and public prompts. This documentation page never asks for or sends your credentials.

03 / CURRENT CONTRACT

One endpoint. Three operations.

POST /api/live/agent · Content-Type: application/json
Authorization: Agent <invitation-token>

Requests made by an external agent
Operation	JSON body	Result
Read state	`{"op":"state"}`	Project context, tool schemas, chat, host status and recent commands.
Send chat	`{"op":"message","body":"Hello"}`	`{"ok":true}`. Send only when requested by the user.
Submit command	`{"op":"command","id":"<UUID>","action":{"actionType":"get_model_summary"}}`	`status: "queued"`. Poll state for the actual result.

Allowed discipline commands

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

Read argument schemas from state.tools and intersect with this role allowlist: the advertised schemas may include both disciplines. Put parameters alongside actionType inside action. The context is a bounded summary, not a complete model export.

SubmitQueuedPoll stateCheck result.success

Stored statuses are pending, claimed, completed and cancelled. Even a completed command can report failure. Pending commands older than five minutes no longer execute and may still appear pending. A claimed command without a result has an unknown outcome.

Retry carefully: retain the command UUID. Reuse it only for the exact same request. Inspect state and the model before retrying an uncertain operation; never automatically repeat a mutation with a fresh UUID. State includes only the latest 30 commands for your invitation.

HTTP errors and recovery

401: Check token format and credential type.
403: Ask the owner to check expiry, revocation, project access and allowed tools.
413: Reduce the request size.
429: Back off rather than polling faster.
503: Ask the operator to check service configuration or availability.
Network timeout: A submitted command may have run. Preserve its ID and inspect the outcome.

04 / EVIDENCE & LIMITS

Examples checked against the implementation

The downloadable plugin is validated with WebCAD's package validator and executed against its SDK bridge with a known model fixture. The published plugin guide is checked against Plugin Studio's instructions.

The Node.js client is tested through the real agent HTTP handler with simulated database responses, including offline hosts, failed commands, cancellation and unknown outcomes. Browser checks cover navigation, downloads and copying instructions.

These checks verify the examples and protocol handling. They do not certify a live deployment, your project's access settings or a production database round-trip. Use the read-only connection check with your own invitation before enabling writes.

Plugin instructions ↗Connection instructions ↗Source repository ↗

Your tools.Your AI.Connected to WebCAD.