From a model to a drawing, over HTTP

• An Occlusia account and an API key, made under API keys in your account. Keep the key in an environment variable: the examples read OCCLUSIA_API_KEY.
• A model: a .skp file saved by SketchUp 2021 or later, an .ifc, an .fbx or an .occs file, 512 MB at most.
• Your graphic standard as a configuration, exported from Occlusia Studio with Export › Configuration (.occc) — or none, and the model is drawn with the default settings.
• Credits, or an early-access account: opening the model and each export cost credits (API and MCP, What it costs).

1. 01

   Open a session

   POST /sessions starts an engine of your own, signed in to your account, and answers its id. An account holds 3 sessions at a time; one ends after 15 minutes unused, or after 8 hours.

2. 02

   Upload the files

   PUT /sessions/{id}/files/{name}, with the file as the raw body: the model, and its configuration. A name is the file's name in the session, never a path on the server.

3. 03

   Open and configure

   The command model.open with {"path": "house.skp"} opens the model and answers its views, in sections. config.set with {"path": "standard.occc"} applies the configuration; a configuration that breaks the format is refused whole, with every error.

4. 04

   Look, if you need to

   preview.render answers a view as a PNG, a JPEG or the SVG itself, up to 2048 pixels on its longer side. An export does not need it.

5. 05

   Export

   export with a format — svg, dxf, pdf, png or jpg —, the sections to draw — a view's name, or a list of them — and out: a file for one drawing, a folder for several. merged makes one PDF of them.

6. 06

   Download, then end the session

   GET /sessions/{id}/files/{name} downloads what the export wrote; DELETE /sessions/{id} ends the session, and its files are deleted with it.

KEY=occ_sk_…                                  # Account › API keys
API=https://api.occlusia.app/v1/engine
AUTH="Authorization: Bearer $KEY"
JSON="Content-Type: application/json"

# 1. A session: an engine of your own, with its own files
S=$(curl -s -X POST $API/sessions -H "$AUTH" | jq -r .id)

# 2. The model and your graphic standard
curl -T house.skp $API/sessions/$S/files/house.skp -H "$AUTH"
curl -T standard.occc $API/sessions/$S/files/standard.occc -H "$AUTH"

# 3. Open the model (1 credit), apply the configuration (free)
curl $API/sessions/$S/commands/model.open -H "$AUTH" -H "$JSON" -d '{"path":"house.skp"}'
curl $API/sessions/$S/commands/config.set -H "$AUTH" -H "$JSON" -d '{"path":"standard.occc"}'

# 4. Export one view as DXF (1 credit per drawing)
curl $API/sessions/$S/commands/export -H "$AUTH" -H "$JSON" \
     -d '{"format":"dxf","sections":"Section A-A","out":"section-a.dxf"}'

# 5. Download it, then end the session: its files are deleted with it
curl -o section-a.dxf $API/sessions/$S/files/section-a.dxf -H "$AUTH"
curl -X DELETE $API/sessions/$S -H "$AUTH"

The examples export the model's first view. sections.list lists them all and says which one is active; objects.list, annotations.list and levels.list list the rest of the model.

• "sections": "Section A-A" exports one view; ["Section A-A", "Ground floor plan"] several, each its own file in the out folder — or one PDF with "merged": true.
• page sets the PDF page of every view — format, orientation, scale_mode fit or custom with its scale_denominator (1:N), margins_mm —, pages one view at a time; image sets a PNG or a JPEG's size or scale, resolution, background and quality.
• export.config reads each view's page setup, and export.setup changes it without exporting, as the export dialog does.
• An export answers the files it wrote and what it cost; GET /sessions/{id}/files lists the session's files.

Every setting a configuration holds can also be set one command at a time: object.set for an object, object.apply_preset for a hatch preset, layers.create and layers.update for the DXF layers, section.set for a view, annotation.set and level.set for notes and spot elevations. engine.schema lists every setting and its values; config.get answers the whole configuration, to keep as an .occc file.

A PDF set can take minutes. Send its command with Prefer: respond-async: it answers 202 and a job at once, and GET /sessions/{id}/jobs/{job} says whether the job is running, done with its result, or failed with its error. GET /sessions/{id}/events streams what the engine does as server-sent events: progress, message, export, job, ended.

• Every refusal is {"error": {"code", "message"}}, with a stable code and the HTTP status that goes with it.
• 429 with cloud_limit or rate_limited, and 503 with busy, carry Retry-After: wait that long, then send the same request again.
• Send an Idempotency-Key with a command: a retry after a lost answer is answered from the first run — never run, never charged twice.
• Every answer carries X-Request-Id: give it with any question about a request.

GET /v1/engine

The engine's version and build, without a key.

GET /v1/engine/openapi.json

The whole API in OpenAPI.

GET /v1/engine/commands

Every command, with its parameters as JSON Schema.

Every route, limit and error code is listed in API and MCP, under The REST API.