Occlusia for programs: the API and AI tools

Everything the web app does, a program can do: open a model, list its objects and views, change their settings, apply a configuration, preview a view, export SVG, DXF, PDF or images. It is the web app's own engine, so the drawings are the app's, byte for byte, and so are its refusals and its prices.

• MCP: an AI tool — Claude, ChatGPT, an editor's assistant — connects to https://api.occlusia.app/v1/mcp with the address alone, and you approve it on occlusia.app. It then works with your models in your words.
• The REST API: https://api.occlusia.app/v1/engine — the engine for a script, a server, a CI job or an app of your own, with an API key or OAuth.

Give your AI tool the address of Occlusia's MCP server. The first time, it sends you to occlusia.app: sign in if needed, check which app asks and what it may do, and allow it. There is no key to copy.

https://api.occlusia.app/v1/mcp

• Claude (claude.ai, the desktop and mobile apps): Settings, Connectors, Add custom connector, then the address above.
• ChatGPT: add a custom MCP server with the address above and OAuth as its authentication.
• Claude Code: claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp, then /mcp to sign in.
• Cursor, VS Code and other tools: add a remote MCP server (Streamable HTTP) with the address; they sign you in the same way.

Every app you allow appears in your account under Connected apps, with what it may do and when it was last used. Disconnect it there and it stops at once. Occlusia emails you the first time an app connects.

Every command is a tool an AI can call: open a model, list its objects, set a hatch, render a preview — answered as an image the model sees —, export. Each tool has a title, says whether it only reads, changes something or replaces a file, and says what it costs.

• A workspace: what the AI opens, sets and exports stays in your workspace from one request to the next, and from one conversation to the next, while it is used. It ends after a while unused, or when the AI resets it.
• Your files: the AI gives you a page to drop your model on — a .skp, .ifc, .fbx or .occs model, a .occp project —, or fetches it from a public link; it hands back what it exported as download links.
• Your account: your credits, their history, the prices and your purchases. When credits run low, the AI can prepare a purchase: it gives you a link to occlusia.app, where you review it and pay — the AI never buys anything.
• A guide and a reference the AI reads on its own (the workflow, every setting and its values), and ready-made prompts: make drawings from a model, export a set, review the account.

The server speaks every current revision of MCP (2026-07-28, and 2025-11-25 back to 2025-03-26). An API key works too, in tools that send it as a header:

claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp \
  --header "Authorization: Bearer occ_sk_…"

A script, a server or a CI job signs in with an API key. Make one in your account, under API keys: a name, how long it lasts, and a sign-in from the last few minutes. The key is shown once; Occlusia keeps only a fingerprint of it.

• A key reads your account and spends your credits; it never manages the account.
• The API keys page lists each key by its name and its last four characters, with when and from which address it was last used. An account holds 20 keys at most.
• Revoking a key stops every program using it at once. Occlusia emails you each time a key is made.

https://api.occlusia.app/v1/engine runs the engine on Occlusia's servers, every request with a key — Authorization: Bearer occ_sk_… — or an app's access token. A session is an engine of your own with its own files: upload a model, run commands, download what they wrote, end the session.

KEY=occ_sk_…
API=https://api.occlusia.app/v1/engine
S=$(curl -s -X POST $API/sessions -H "Authorization: Bearer $KEY" | jq -r .id)
curl -T house.skp $API/sessions/$S/files/house.skp -H "Authorization: Bearer $KEY"
curl $API/sessions/$S/commands/model.open -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"path":"house.skp"}'
curl $API/sessions/$S/commands/export -H "Authorization: Bearer $KEY" \
     -H 'Content-Type: application/json' -d '{"format":"pdf","sections":"Section AA","out":"section.pdf"}'
curl -o section.pdf $API/sessions/$S/files/section.pdf -H "Authorization: Bearer $KEY"
curl -X DELETE $API/sessions/$S -H "Authorization: Bearer $KEY"

The routes, under /v1/engine; … is /sessions/{id}:

POST /sessions

Opens a session. An account holds 3 at a time; one ends after 15 minutes unused or 8 hours.

PUT …/files/{name}

Uploads a file, the raw body: 512 MB at most, 2 GB per session.

POST …/commands/{command}

Runs a command, its parameters the JSON body; the answer is the command's. With Prefer: respond-async, a job is answered at once.

GET …/jobs/{job}

A job: running, done with its result, or failed with its error.

GET …/events

What the engine does, as server-sent events: progress, messages, exports.

GET …/files/{name}

Downloads a file of the session. GET …/files lists them, DELETE deletes one.

POST …/links

A link that uploads or downloads one file for 15 minutes, without the key; an upload link opened in a browser is a page to drop the file on.

DELETE /sessions/{id}

Ends the session; its files are deleted with it.

GET /commands

Every command with its JSON Schema; the whole API in OpenAPI at /openapi.json.

A file parameter names a file of the session — "path": "house.skp", "out": "set.pdf" —, never a path on the server. Objects are named as in the model browser — by name, or by path (Walls/South wall) —, views by their name. One command runs at a time in a session; what computes — a model opened, a drawing, an export — runs two at a time per account and waits up to a minute for its turn, while a list or a setting never waits. 600 requests a minute per key.

• Idempotency: send Idempotency-Key with a command and a retry after a lost answer is answered from the first run — never run, never charged twice.
• Request ids and limits: every answer carries X-Request-Id (yours, when you send one) and RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset.
• The account: GET /v1/auth/me, /v1/account/credits, /v1/account/credits/history and /v1/account/credits/purchases read it with the same key.
• Export setup: export.config and export.setup read and change each view's PDF page and where the drawing sits on the sheet, as the export dialog does.

Every refusal is {"error": {"code", "message"}} with a stable code: invalid_api_key (401), insufficient_credits (402), session_not_found (404), invalid_params (422), rate_limited, session_limit and cloud_limit (429: the early-access allowance is used up until its Retry-After), busy (503: try again after its Retry-After), credits_unavailable (503: nothing ran, try again), and the command's own codes when it refuses.

An app of yours can act for its users' Occlusia accounts with OAuth 2.1: the authorization code flow with PKCE (S256), public clients. The authorization server's metadata is at https://api.occlusia.app/.well-known/oauth-authorization-server; register your client there, or name it by the https address of a client metadata document.

• Scopes: engine — open, configure, draw and export, spending the user's credits —, and account — read the account, its credits and purchases.
• Ask for the resource you call (resource=https://api.occlusia.app/v1/engine or …/v1/mcp): a token works only there.
• An access token lasts an hour; refresh tokens rotate at each use. The user sees your app under Connected apps and can disconnect it there.

• Occlusia stores an API key as a fingerprint, never as itself: a lost key cannot be shown again, only revoked.
• A connected app holds tokens Occlusia keeps only as fingerprints; they open only what you allowed, and nothing once you disconnect the app.
• Each API session runs in an engine of its own, under a system user of its own, with no network but Occlusia's services. Its files are deleted when it ends.
• A file fetched from a link comes from the public internet only, never from a private network.
• Making a key or connecting an app asks for a sign-in from the last few minutes, and Occlusia emails you each time.