Occlusia voor programma’s: de API en AI-tools

Alles wat de webapp doet, kan een programma ook: een model openen, de objecten en aanzichten ervan opsommen, hun instellingen wijzigen, een configuratie toepassen, een aanzicht voorvertonen, exporteren naar SVG, DXF, PDF of afbeeldingen. Het is de eigen engine van de webapp: de tekeningen zijn die van de app, byte voor byte, net als de weigeringen en de prijzen.

• MCP: een AI-tool — Claude, ChatGPT, de assistent van een editor — maakt verbinding met https://api.occlusia.app/v1/mcp met alleen het adres, en u keurt hem goed op occlusia.app. Daarna werkt hij met uw modellen, in uw eigen woorden.
• De REST-API: https://api.occlusia.app/v1/engine — de engine voor een script, een server, een CI-taak of een eigen app, met een API-sleutel of OAuth.

Geef uw AI-tool het adres van de MCP-server van Occlusia. De eerste keer stuurt hij u naar occlusia.app: meld u aan als dat nodig is, controleer welke app het vraagt en wat die mag doen, en sta hem toe. Er hoeft geen sleutel gekopieerd te worden.

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

• Claude (claude.ai, de desktop- en mobiele apps): Settings, Connectors, Add custom connector, dan het adres hierboven.
• ChatGPT: voeg een aangepaste MCP-server toe met het adres hierboven en OAuth als authenticatie.
• Claude Code: claude mcp add --transport http occlusia https://api.occlusia.app/v1/mcp, dan /mcp om u aan te melden.
• Cursor, VS Code en andere tools: voeg een externe MCP-server (Streamable HTTP) toe met het adres; ze melden u op dezelfde manier aan.

Elke app die u toestaat, verschijnt in uw account onder Gekoppelde apps, met wat hij mag doen en wanneer hij het laatst is gebruikt. Ontkoppel hem daar en hij stopt meteen. Occlusia stuurt u een e-mail de eerste keer dat een app wordt gekoppeld.

Elke opdracht is een tool die een AI kan aanroepen: een model openen, de objecten opsommen, een arcering instellen, een voorvertoning maken — beantwoord als een afbeelding die het model ziet —, exporteren. Elke tool heeft een titel, zegt of hij alleen leest, iets wijzigt of een bestand vervangt, en zegt wat hij kost.

• Een werkruimte: wat de AI opent, instelt en exporteert, blijft in uw werkruimte van het ene verzoek naar het volgende, en van het ene gesprek naar het volgende, zolang ze wordt gebruikt. Ze eindigt na een tijd zonder gebruik, of wanneer de AI haar reset.
• Uw bestanden: de AI geeft u een pagina om uw model naartoe te slepen — een .skp-, .ifc-, .fbx- of .occs-model, een .occp-project —, of haalt het op via een openbare link; wat hij exporteerde, geeft hij terug als downloadlinks.
• Uw account: uw credits, hun geschiedenis, de prijzen en uw aankopen. Raken de credits bijna op, dan kan de AI een aankoop voorbereiden: hij geeft u een link naar occlusia.app, waar u die controleert en betaalt — de AI koopt nooit iets.
• Een handleiding en een naslagwerk die de AI zelf leest (de werkwijze, elke instelling en haar waarden), en kant-en-klare prompts: tekeningen maken van een model, een tekeningenset exporteren, het account nakijken.

De server spreekt elke actuele revisie van MCP (2026-07-28, en 2025-11-25 terug tot 2025-03-26). Een API-sleutel werkt ook, in tools die hem als header meesturen:

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

Een script, een server of een CI-taak meldt zich aan met een API-sleutel. Maak er een in uw account, onder API-sleutels: een naam, hoe lang hij geldig is, en een aanmelding van de laatste minuten. De sleutel wordt één keer getoond; Occlusia bewaart er alleen een vingerafdruk van.

• Een sleutel leest uw account en besteedt uw credits; hij beheert het account nooit.
• De pagina API-sleutels toont elke sleutel met zijn naam en zijn laatste vier tekens, met wanneer en vanaf welk adres hij het laatst is gebruikt. Een account heeft hoogstens 20 sleutels.
• Een sleutel intrekken stopt meteen elk programma dat hem gebruikt. Occlusia stuurt u een e-mail telkens wanneer een sleutel wordt gemaakt.

https://api.occlusia.app/v1/engine draait de engine op de servers van Occlusia, elk verzoek met een sleutel — Authorization: Bearer occ_sk_… — of het toegangstoken van een app. Een sessie is een eigen engine met eigen bestanden: upload een model, voer opdrachten uit, download wat ze schreven, beëindig de sessie.

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"

De routes, onder /v1/engine; … staat voor /sessions/{id}:

POST /sessions

Opent een sessie. Een account heeft er 3 tegelijk; een sessie eindigt na 15 minuten zonder gebruik of na 8 uur.

PUT …/files/{name}

Uploadt een bestand, de ruwe body: hoogstens 512 MB, 2 GB per sessie.

POST …/commands/{command}

Voert een opdracht uit, met de parameters als JSON-body; het antwoord is dat van de opdracht. Met Prefer: respond-async wordt meteen een taak geantwoord.

GET …/jobs/{job}

Een taak: bezig, klaar met het resultaat, of mislukt met de fout.

GET …/events

Wat de engine doet, als server-sent events: voortgang, berichten, exports.

GET …/files/{name}

Downloadt een bestand van de sessie. GET …/files geeft ze allemaal, DELETE verwijdert er een.

POST …/links

Een link die één bestand 15 minuten lang uploadt of downloadt, zonder de sleutel; een uploadlink die in een browser wordt geopend, is een pagina om het bestand naartoe te slepen.

DELETE /sessions/{id}

Beëindigt de sessie; de bestanden worden ermee verwijderd.

GET /commands

Elke opdracht met haar JSON Schema; de hele API in OpenAPI op /openapi.json.

Een bestandsparameter benoemt een bestand van de sessie — "path": "house.skp", "out": "set.pdf" —, nooit een pad op de server. Objecten worden benoemd zoals in de modelbrowser — met hun naam of hun pad (Walls/South wall) —, aanzichten met hun naam. Eén opdracht tegelijk per sessie; berekeningen — een geopend model, een tekening, een export — draaien met twee tegelijk per account en wachten tot een minuut op hun beurt, terwijl een lijst of een instelling nooit wacht. 600 verzoeken per minuut per sleutel.

• Idempotentie: stuur Idempotency-Key mee met een opdracht, en een nieuwe poging na een verloren antwoord krijgt het antwoord van de eerste uitvoering — nooit twee keer uitgevoerd, nooit twee keer aangerekend.
• Verzoek-id’s en limieten: elk antwoord bevat X-Request-Id (de uwe, als u er een meestuurt) en RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset.
• Het account: GET /v1/auth/me, /v1/account/credits, /v1/account/credits/history en /v1/account/credits/purchases lezen het met dezelfde sleutel.
• Exportinstelling: export.config en export.setup lezen en wijzigen de PDF-pagina van elk aanzicht en waar de tekening op het blad staat, zoals het exportvenster doet.

Elke weigering is {"error": {"code", "message"}} met een vaste code: invalid_api_key (401), insufficient_credits (402), session_not_found (404), invalid_params (422), rate_limited, session_limit en cloud_limit (429: het tegoed van de vroege toegang is op tot de Retry-After), busy (503: probeer opnieuw na de Retry-After), credits_unavailable (503: er is niets uitgevoerd, probeer opnieuw), en de eigen codes van de opdracht als die weigert.

Een app van u kan met OAuth 2.1 optreden namens de Occlusia-accounts van zijn gebruikers: de autorisatiecode-flow met PKCE (S256), publieke clients. De metadata van de autorisatieserver staan op https://api.occlusia.app/.well-known/oauth-authorization-server; registreer uw client daar, of benoem hem met het https-adres van een clientmetadatadocument.

• Scopes: engine — openen, configureren, tekenen en exporteren, met de credits van de gebruiker —, en account — het account, de credits en de aankopen lezen.
• Vraag de resource aan die u aanroept (resource=https://api.occlusia.app/v1/engine of …/v1/mcp): een token werkt alleen daar.
• Een toegangstoken is een uur geldig; refreshtokens roteren bij elk gebruik. De gebruiker ziet uw app onder Gekoppelde apps en kan hem daar ontkoppelen.

• Occlusia bewaart een API-sleutel als vingerafdruk, nooit als zichzelf: een verloren sleutel kan niet opnieuw worden getoond, alleen ingetrokken.
• Een gekoppelde app heeft tokens die Occlusia alleen als vingerafdrukken bewaart; ze openen alleen wat u hebt toegestaan, en niets meer zodra u de app ontkoppelt.
• Elke API-sessie draait in een eigen engine, onder een eigen systeemgebruiker, zonder ander netwerk dan de diensten van Occlusia. De bestanden worden verwijderd wanneer ze eindigt.
• Een bestand dat via een link wordt opgehaald, komt alleen van het openbare internet, nooit van een privénetwerk.
• Een sleutel maken of een app koppelen vraagt om een aanmelding van de laatste minuten, en Occlusia stuurt u telkens een e-mail.