# Shapediver Geometry Backend

> Use this skill when the user needs to write code with a ShapeDiver Geometry Backend SDK: TypeScript/JavaScript using @shapediver/sdk.geometry-api-sdk-v2, Python using geometry-api-v2, or PHP using GeometryBackendSdkPhp / shapediver/geometry-api-v2. Covers SDK setup, session lifecycle, tickets, JWTs, modelViewUrl, parameters, outputs, exports, file parameters, asset downloads, error handling, SDK selection by language, and Geometry Backend architecture questions. Prefer SDK code over direct REST. Do NOT use this skill for ShapeDiver Viewer browser apps, App Builder iframe/theme/fork workflows, or Grasshopper modeling.

- Skill: `shapediver/shapediver-geometry-backend` (Agent Skill, multi-file: 11 files)
- Install (CLI): `npx skillmds@latest add shapediver/shapediver-geometry-backend`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shapediver/shapediver-geometry-backend/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: shapediver (https://skillmd.com/u/shapediver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shapediver/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](references/sdk-typescript.md) |
| Python | `geometry-api-v2` | `pip install geometry-api-v2` | [references/sdk-python.md](references/sdk-python.md) |
| PHP | `shapediver/geometry-api-v2` | `composer require shapediver/geometry-api-v2` | [references/sdk-php.md](references/sdk-php.md) |

Canonical TypeScript imports:

```ts
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.

```ts
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`.

```ts
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:

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

Exports:

```ts
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:

```ts
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

```ts
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](references/sdk-typescript.md) for Node.js,
  TypeScript, JavaScript, `Configuration`, `.data` access, and polling helpers.
- Read [references/sdk-python.md](references/sdk-python.md) for Python syntax.
- Read [references/sdk-php.md](references/sdk-php.md) for PHP syntax and Composer setup.
- Read [references/auth-and-credentials.md](references/auth-and-credentials.md) when the
  main problem is ticket vs JWT vs `modelViewUrl`.
- Read [references/uploads-and-downloads.md](references/uploads-and-downloads.md) for file
  parameters, presigned uploads, output/export downloads, and session-bound asset handling.
- Read [references/error-handling.md](references/error-handling.md) for response-error
  handling, session expiry, and permission-gated fields.
- Read [references/geometry-backend-concepts.md](references/geometry-backend-concepts.md)
  only for deeper architecture or lifecycle questions.
- Read [references/openapi-on-demand.md](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:

```bash
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`.