Shapediver geometry backend

ShapeDiver Geometry Backend SDKs

Prerequisite: This skill assumes you have already read and followed the shapediver-router skill. If you arrived here directly, stop — read shapediver-router first. It selects the correct integration strategy and gathers required credentials before any implementation skill is read.

This is the SDK implementation skill for Geometry Backend runtime code. Use it to generate working code for sessions, outputs, exports, file parameters, downloads, and GB-side troubleshooting.

Scope And Non-Goals

Use this skill when the task is GB runtime code and the main job is to write correct SDK usage.

Use a neighboring skill instead when:

• PB must still resolve modelViewUrl, ticket, or JWT: shapediver-platform-geometry-workflows
• the task is PB-only resource management: shapediver-platform-backend
• the task is Viewer/App Builder browser work: shapediver-viewer or shapediver-appbuilder*

Do not turn this skill into:

• Viewer browser code,
• PB control-plane code,
• App Builder guidance,
• Grasshopper authoring advice.

Canonical Packages And Imports

Choose one SDK based on the user's runtime and stay inside that SDK's idioms.

Language/runtime	Package	Install	Load next
TypeScript / JavaScript / Node.js	@shapediver/sdk.geometry-api-sdk-v2	npm i @shapediver/sdk.geometry-api-sdk-v2	references/sdk-typescript.md
Python	geometry-api-v2	pip install geometry-api-v2	references/sdk-python.md
PHP	shapediver/geometry-api-v2	composer require shapediver/geometry-api-v2	references/sdk-php.md

Canonical TypeScript imports:

import { Configuration, SessionApi, OutputApi, ExportApi, FileApi, UtilsApi, processError, ResponseError, type ReqCustomization, type ReqExport } from "@shapediver/sdk.geometry-api-sdk-v2";

Rules:

• The v2 suffix is part of the package name: @shapediver/sdk.geometry-api-sdk-v2.
• Prefer the latest available Geometry SDK package version. Do not downgrade or omit the versioned package name unless the user explicitly requires an older package.
• Do not invent alternate package names or import paths.
• Do not drop to raw REST when the SDK already covers the operation.
• Do not mix TypeScript, Python, and PHP patterns in one answer.

Canonical Configuration And Authentication

Use the model's real modelViewUrl. Do not guess the host.

const config = new Configuration({
  basePath: modelViewUrl,
  accessToken: jwt, // optional unless strong authorization is enabled
});

Credential rules:

• New GB sessions normally need a ticket that was generated by the Platform Backend.
• Those tickets become usable only after the Platform-side model exists and its Grasshopper file has been uploaded and checked successfully.
• Use backendTicket for server, CLI, and automation flows.
• Use ticket only for embedding/browser-oriented flows.
• Do not use authorTicket unless the workflow explicitly requires elevated authoring access and there is no safer ticket choice.
• Use accessToken: jwt when the workflow needs GB authorization before any session exists, or when the model's require_token property means the session flow must use a token in addition to the ticket.
• Keep tickets and JWTs server-side.
• If modelViewUrl, backend ticket/JWT, or current metadata still need to be resolved from Platform inputs, stop and load shapediver-platform-geometry-workflows first.

Canonical Session Lifecycle

Create one session, reuse it for related work, then close it in finally.

const sessionApi = new SessionApi(config);
const session = (await sessionApi.createSessionByTicket(backendTicket)).data;
try {
  console.log(session.sessionId, session.parameters ?? {}, session.outputs ?? {}, session.exports ?? {});
} finally {
  await sessionApi.closeSession(session.sessionId);
}

Use createSessionByModel(guid) only when the user actually has a JWT-based model flow that supports it. Do not substitute slug or PB model id there.

Canonical Request And Response Patterns

Generated SDK calls return wrapped responses. Read DTOs from .data and treat nested sections as optional.

Outputs:

const params: ReqCustomization = { [parameterId]: parameterValue };
const outputResult = (await new OutputApi(config).computeOutputs(session.sessionId, params)).data;
const output = outputResult.outputs?.[outputId];

Exports:

const exportReq: ReqExport = {
  parameters: { [parameterId]: parameterValue },
  exports: [exportId],
  max_wait_time: 120_000,
};
const exportResult = (await new ExportApi(config).computeExports(session.sessionId, exportReq)).data;

Use UtilsApi.submitAndWaitForOutput(...) or UtilsApi.submitAndWaitForExport(...) when the answer should wait for delayed results instead of returning raw polling state.

File parameters:

const upload = (await new FileApi(config).uploadFile(session.sessionId, {
  [fileParameterId]: { filename, format: mimeType, size: byteLength },
})).data;
const uploaded = upload.asset.file[fileParameterId];
await new UtilsApi(config).uploadAsset(uploaded.href, fileBytes, uploaded.headers);
const fileParams: ReqCustomization = { [fileParameterId]: uploaded.id };

Downloads:

• Use output/export content from the SDK response.
• Use SDK download helpers such as UtilsApi.downloadAsset(...) when a full asset URL is present.
• Do not invent permanent asset URLs.
• Missing outputs, exports, content, or upload asset blocks usually means metadata, session-state, or permission issues; do not assume they always exist.

Canonical Error Handling

try {
  // SDK calls
} catch (err) {
  const shapediverError = await Promise.resolve(processError(err as Error));
  if (shapediverError instanceof ResponseError) {
    console.error(shapediverError.status, shapediverError.type, shapediverError.message, shapediverError.description);
  } else {
    console.error(shapediverError);
  }
}

Surface ShapeDiver-specific failure details. Do not replace them with a generic "request failed" message.

High-Frequency Anti-Patterns

• Do not hardcode a shared GB host when the real modelViewUrl is known.
• Do not use embedding tickets for backend automation.
• Do not send Platform bearer tokens to GB endpoints.
• Do not assume outputs, exports, content, or upload asset sections always exist.
• Do not open one GB session per tiny operation.
• Do not forget closeSession(...) in finally.
• Do not use { id: exportId }; current export requests use exports: [exportId].
• Do not attach GB bearer auth to the presigned upload URL.
• Do not invent parameter, output, export, session, ticket, JWT, host, or asset values.

Reference Loading Map

• Read references/sdk-typescript.md for Node.js, TypeScript, JavaScript, Configuration, .data access, and polling helpers.
• Read references/sdk-python.md for Python syntax.
• Read references/sdk-php.md for PHP syntax and Composer setup.
• Read references/auth-and-credentials.md when the main problem is ticket vs JWT vs modelViewUrl.
• Read references/uploads-and-downloads.md for file parameters, presigned uploads, output/export downloads, and session-bound asset handling.
• Read references/error-handling.md for response-error handling, session expiry, and permission-gated fields.
• Read references/geometry-backend-concepts.md only for deeper architecture or lifecycle questions.
• Read references/openapi-on-demand.md only when the SDK reference is still insufficient or the user explicitly asks for endpoint/schema verification.

Placeholders

Use explicit placeholders when the user has not supplied concrete values:

Value	Placeholder
Backend ticket	PASTE_YOUR_BACKEND_TICKET_HERE
Model view URL	PASTE_YOUR_MODEL_VIEW_URL_HERE
JWT	PASTE_YOUR_JWT_HERE
Parameter id	PARAMETER_ID
Output id	OUTPUT_ID
Export id	EXPORT_ID
File parameter id	FILE_PARAMETER_ID

If the user provides a model slug plus Platform API access key ID and secret, the shared repository helper can retrieve current metadata:

node scripts/get-model-info.js <accessKeyId> <accessKeySecret> <slug>

Use the returned model.backendTicket, model.modelViewUrl, parameters, outputs, and exports. The helper closes its metadata session after reading it.

Exit Criteria

• The answer uses the correct SDK package and import style for the user's language.
• The SDK is configured with the real modelViewUrl, not a guessed default host.
• The answer uses the correct runtime credential: backend ticket for backend work, JWT when required, and never a PB bearer token as a GB credential.
• The code reads DTOs from wrapped SDK responses correctly and checks permission-gated sections defensively.
• Related GB work reuses one session and closes it explicitly in the cleanup path.
• Output/export/file-upload request shapes match the current SDK patterns.
• Downloads and uploads use the SDK-returned asset data instead of invented URLs.
• Any missing PB prerequisites are called out and routed to shapediver-platform-geometry-workflows.