Zoo Documentation

https://zoo.dev/docs
Admin
Documentation for the Zoo product suite, catering to mechanical designers and software developers...
Tokens:1,778,107
Snippets:13,558
Trust Score:9.4
Update:5 months ago
Show doc for...
Tokens:
Raw
### Create and Extrude a Simple Profile

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-startProfile

Demonstrates creating a sketch on the XZ plane, starting a profile at the origin, drawing a square, closing the profile, and then extruding it. This example shows a basic usage of startProfile.

```kcl
exampleSketch = startSketchOn(XZ)
  |> startProfile(at = [0, 0])
  |> line(end = [10, 0])
  |> line(end = [0, 10])
  |> line(end = [-10, 0])
  |> close()

example = extrude(exampleSketch, length = 5)
```

--------------------------------

### 200 OK Response

Source: https://zoo.dev/docs/developer-tools/api/payments/update-the-subscription-for-an-org?lang=typescript

This is an example of a successful response when updating an organization's subscription. It includes details about the setup intent and the updated modeling app.

```json
{
  "action_client_secret": "HHVQeTATuKMWHeRxMkAVHX",
  "action_type": "setup_intent",
  "modeling_app": {
    "annual_discount": 2,
    "billing_mode": "standard",
    "description": "",
    "display_name": "AP7oTuqmpxM8CRWe3JFEJy8cgbV3q0",
    "endpoints_included": [
      "ml"
    ],
    "features": [
      {
        "info": "5GPleqqHm6zE8z"
      }
    ],
    "ml_custom_models": false,
    "monthly_pay_as_you_go_api_credits": 17,
    "monthly_pay_as_you_go_api_credits_monetary_value": "88.97",
    "name": "fig2FyKG50j",
    "pay_as_you_go_api_credit_price": "76.71",
    "price": {
      "interval": "year",
      "price": "67.04",
      "type": "flat"
    },
    "share_links": [
      "organization_only"
    ],
    "support_tier": "standard_email",
    "training_data_behavior": "always",
    "type": {
      "saml_sso": false,
      "type": "organization"
    },
    "zoo_tools_included": [
      "text_to_cad"
    ]
  }
}
```

--------------------------------

### Set Up Python Virtual Environment and Install KittyCAD

Source: https://zoo.dev/docs/developer-tools/tutorials/beginner-onboarding-py

This command sequence sets up a Python virtual environment, installs the KittyCAD library, and then executes a conversion script. Replace 'YOUR-API-TOKEN' with your actual KittyCAD API token.

```bash
export ZOO_API_TOKEN="YOUR-API-TOKEN"
pip3 install virtualenv
python3 -m venv venv
source venv/bin/activate
pip3 install kittycad
python3 tutorials/beginner_tutorial/convert.py

```

--------------------------------

### Example Usage of segStart in Sketching

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-segStart

Demonstrates how to use the segStart function within a KCL sketch to define a cylinder's profile based on the starting point of a line segment. This example requires prior sketch setup and line definition.

```kcl
w = 15
cube = startSketchOn(XY)
  |> startProfile(at = [0, 0])
  |> line(end = [w, 0], tag = $line1)
  |> line(end = [0, w], tag = $line2)
  |> line(end = [-w, 0], tag = $line3)
  |> line(end = [0, -w], tag = $line4)
  |> close()
  |> extrude(length = 5)

fn cylinder(radius, tag) {
  return startSketchOn(XY)
    |> startProfile(at = [0, 0])
    |> circle(radius = radius, center = segStart(tag))
    |> extrude(length = radius)
}

cylinder(radius = 1, tag = line1)
cylinder(radius = 2, tag = line2)
cylinder(radius = 3, tag = line3)
cylinder(radius = 4, tag = line4)


```

--------------------------------

### Get an org - Response Example

Source: https://zoo.dev/docs/developer-tools/api/orgs/get-an-org?lang=go

This is an example of a successful response (200 OK) when retrieving organization details. It includes various properties describing the organization.

```json
{
  "allow_users_in_domain_to_auto_join": true,
  "aws_external_id": "ffdaca8b-33e3-4ec4-af3b-98c0850b543a",
  "billing_email": "d4Nc6Uaop@el1tes.com",
  "billing_email_verified": "2026-05-06T12:31:37.346Z",
  "block": "payment_method_failed",
  "can_train_on_data": true,
  "created_at": "2026-05-06T12:31:37.346Z",
  "domain": "r1xTV8jX",
  "id": "49e57bcf-5077-4037-8753-4eac799ec834",
  "image": "https://Ag7G6QGS.v3soBaF.com/FcCJv9Sp/1OLrXnG",
  "name": "86LN1DXhJALTZqX485D64w9",
  "phone": "+1-306-438-7433",
  "stripe_id": "1Oo3v",
  "updated_at": "2026-05-06T12:31:37.346Z"
}
```

--------------------------------

### Set Up and Run KittyCAD Python Script

Source: https://zoo.dev/docs/developer-tools/tutorials/beginner-onboarding-py

This command sequence sets your API token, installs virtual environment tools, creates and activates a virtual environment, installs the KittyCAD library, and finally runs the conversion script. Remember to replace `YOUR-API-TOKEN` with your actual token.

```powershell
$env:ZOO_API_TOKEN = "YOUR-API-TOKEN"
pip install virtualenv
python -m venv venv
.\venv\Scripts\Activate.ps1
pip install kittycad
python .\tutorials\beginner_tutorial\convert.py

```

--------------------------------

### Multiple Profiles Example (Correct)

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-startSketchOn

Demonstrates the correct way to create multiple profiles using separate pipelines and then extruding them as an array.

```APIDOC
### Multiple Profiles (Correct)

Instead, use separate pipelines, and extrude an array of them all.

```kcl
sketch1 = startSketchOn(XY)
squareProfile1 = startProfile(sketch1, at = [0, 0])
  |> line(end = [10, 0])
  |> line(end = [0, 10])
  |> line(end = [-10, 0])
  |> close()
squareProfile2 = startProfile(sketch1, at = [20, 0])
  |> line(end = [10, 0])
  |> line(end = [0, 10])
  |> line(end = [-10, 0])
  |> close()
twoCubes = extrude([squareProfile1, squareProfile2], length = 10)
```
```

--------------------------------

### Get User Subscription (TypeScript)

Source: https://zoo.dev/docs/developer-tools/api/payments/get-the-subscription-for-a-user

This TypeScript example uses `fetch` to get subscription data. Remember to replace `YOUR_API_TOKEN` with your valid API token.

```typescript
const token = "YOUR_API_TOKEN";

fetch("https://api.zoo.dev/user/payment/subscriptions", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${token}`
  }
})
  .then(response => response.json())
  .then(data => console.log(data))
  .catch(error => console.error("Error:", error));
```

--------------------------------

### Curve Endpoint Retrieval

Source: https://zoo.dev/docs/developer-tools/api/modeling/open-a-websocket-which-accepts-modeling-commands?lang=typescript

Command to get the start and end points of a curve.

```APIDOC
## Curve Endpoint Retrieval

### `curve_get_end_points`

#### Description
Retrieves the start and end points of a curve.

#### Data Properties
* `end` (object, optional): The end point of the curve.
  * `x` (number, optional)
  * `y` (number, optional)
  * `z` (number, optional)
* `start` (object, optional): The start point of the curve.
  * `x` (number, optional)
  * `y` (number, optional)
  * `z` (number, optional)
* `type` (string, optional): The type of the response, expected to be `curve_get_end_points`.
```

--------------------------------

### Example Response for Get Organization Shortlinks

Source: https://zoo.dev/docs/developer-tools/api/orgs/get-the-shortlinks-for-an-org?lang=curl

This is an example of a successful response when retrieving shortlinks for an organization. It includes a list of shortlinks with their details and a token for fetching the next page.

```json
{
  "items": [
    {
      "created_at": "2026-05-06T12:26:52.368Z",
      "id": "1dfe53ad-7e30-4d99-ac72-5c5a5c823498",
      "key": "lD",
      "org_id": "c9c7fce6-4bf9-4188-b6ec-e8910c6e7569",
      "password_hash": "bY",
      "restrict_to_org": true,
      "updated_at": "2026-05-06T12:26:52.369Z",
      "user_id": "8d70623a-6476-4f19-a406-ddc285b6a812",
      "value": "https://mMbeCka7ypHZ.XnABMV8OX.com/vBtUzfRb7/xMG6JsH9g5DI"
    }
  ],
  "next_page": "l3G9"
}
```

--------------------------------

### Install KittyCAD Go Client

Source: https://zoo.dev/docs/developer-tools/api?lang=go

Use this command to install the official Go client library for the KittyCAD API. Ensure you have Go installed and configured.

```bash
$ go get github.com/kittycad/kittycad.go
```

--------------------------------

### Create a Circle and Extrude

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-circle

Demonstrates how to create a circle with a specified center and radius, then extrude it. This example uses the `startSketchOn` and `circle` functions.

```kcl
exampleSketch = startSketchOn(-XZ)
  |> circle(center = [0, 0], radius = 10)

example = extrude(exampleSketch, length = 5)

```

--------------------------------

### Curve Get End Points Command

Source: https://zoo.dev/docs/developer-tools/api/modeling/open-a-websocket-which-accepts-modeling-commands?lang=python

Retrieves the start and end points of a curve.

```APIDOC
## Curve Get End Points

### Description
This command retrieves the start and end points (coordinates) of a specified curve.

### Command Type
`curve_get_end_points`

### Parameters
#### Request Body
- **data** (object) - Required - This object is typically empty for this command, as it operates on the current curve context.

### Request Example
```json
{
  "type": "curve_get_end_points",
  "data": {}
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the start and end points of the curve.
  - **start** (object) - Optional - The starting point of the curve.
    - **x** (number) - Optional - X-coordinate.
    - **y** (number) - Optional - Y-coordinate.
    - **z** (number) - Optional - Z-coordinate.
  - **end** (object) - Optional - The ending point of the curve.
    - **x** (number) - Optional - X-coordinate.
    - **y** (number) - Optional - Y-coordinate.
    - **z** (number) - Optional - Z-coordinate.
  - **type** (string) - The type of the response, e.g., `curve_get_end_points`.

#### Response Example
```json
{
  "type": "curve_get_end_points",
  "data": {
    "start": {"x": 0.0, "y": 0.0, "z": 0.0},
    "end": {"x": 1.0, "y": 1.0, "z": 0.0}
  }
}
```
```

--------------------------------

### Curve Get End Points

Source: https://zoo.dev/docs/developer-tools/api/modeling/open-a-websocket-which-accepts-modeling-commands?lang=typescript

Finds the start and end points of a specified curve.

```APIDOC
## curve_get_end_points

### Description
Find the start and end of a curve.

### Type
object
```

--------------------------------

### Importing a STEP File (Initialization Stage)

Source: https://zoo.dev/docs/kcl-lang/foreign-imports

Demonstrates the import statement for a STEP file, which initiates the read and background render process without blocking script execution.

```kcl
import "tests/inputs/cube.step" as cube


```

--------------------------------

### Curve Get End Points

Source: https://zoo.dev/docs/developer-tools/api/modeling/open-a-websocket-which-accepts-modeling-commands?lang=curl

Finds the start and end points of a specified curve.

```APIDOC
## curve_get_end_points

### Description
Find the start and end of a curve.

### Method
(Implicitly via WebSocket message)

### Endpoint
(Implicitly via WebSocket message)

### Parameters
#### Request Body
- **curve_id** (string / UUID) - Optional - ID of the curve being queried.
- **type** (string) - Optional - Possible values: `curve_get_end_points`
```

--------------------------------

### API Authentication Examples

Source: https://zoo.dev/docs/developer-tools/api/authentication?lang=typescript

Examples demonstrating how to authenticate API requests using either a client instance with a provided token or by leveraging the KITTYCAD_TOKEN environment variable.

```typescript
async function ExampleWithClient() {
  const client = new Client('your-token');
  const response = await meta.ping({ client });
  if ('error_code' in response) throw 'error';
  console.log(response.message); // 'pong'
}

// - OR -

// Your token will be parsed from the environment
// variable: 'KITTYCAD_TOKEN'.
async function ExampleWithOutClient() {
  const response = await meta.ping();
  if ('error_code' in response) throw 'error';
  console.log(response.message); // 'pong'
}
```

--------------------------------

### Project Creation Response Example

Source: https://zoo.dev/docs/developer-tools/api/projects/create-a-draft-project-for-the-authenticated-user?lang=rust

This is an example of a successful response when creating a project, detailing the project's metadata and status.

```json
{
  "category_ids": [
    "4001796d-eb70-4557-b6d1-aa290467bb26"
  ],
  "created_at": "2026-05-06T12:33:29.455Z",
  "description": "",
  "entrypoint_path": "bdnUtGzCjfaJ7qcy8egl8",
  "files": [
    {
      "byte_size": 14,
      "content_type": "ULvKOlXOxG4i7qw7x7NnGD",
      "created_at": "2026-05-06T12:33:29.456Z",
      "file_role": "project_toml",
      "id": "0bff8e68-cb86-40cf-92fe-2c2f26440cf5",
      "relative_path": "x1BQsRqdQOm58CpPMs",
      "sha256": "XE4BI442DFpXtnHw4w60sO62KDQFP",
      "sort_order": 1,
      "updated_at": "2026-05-06T12:33:29.456Z"
    }
  ],
  "id": "9f3b192d-1640-44dd-9641-3672a8eaf8dc",
  "preview_status": "failed",
  "preview_url": "ZqCysfSUFDN6Ui5lx1RK",
  "project_toml_path": "jLbatvlCsSyLFtqnuFMRBZvhymz",
  "publication": {
    "has_unpublished_changes": false,
    "last_published_at": "2026-05-06T12:33:29.456Z",
    "last_published_version_id": "5377cc62-8ee9-4719-8a02-309ab0ca21bf",
    "submitted_at": "2026-05-06T12:33:29.456Z"
  },
  "publication_status": "deleted",
  "title": "ttaURCL",
  "updated_at": "2026-05-06T12:33:29.456Z"
}

```

--------------------------------

### Example Usage of segStartX in Sketch Definition

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-segStartX

This example demonstrates how to use segStartX within a sketch definition to dynamically set the end point of a line based on the start of a previously tagged segment.

```kcl
exampleSketch = startSketchOn(XZ)
  |> startProfile(at = [0, 0])
  |> line(end = [20, 0], tag = $thing)
  |> line(end = [0, 5])
  |> line(end = [20 - segStartX(thing), 0])
  |> line(end = [-20, 10])
  |> close()

example = extrude(exampleSketch, length = 5)

```

--------------------------------

### Sketch Creation and Profile Start Extraction

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-profileStart

Demonstrates creating a sketch, defining a profile using angled and straight lines, and then using profileStart to close the profile. This example shows how to construct a complex shape and utilize the profileStart function to reference the profile's origin.

```kcl
sketch001 = startSketchOn(XY)
  |> startProfile(at = [5, 2])
  |> angledLine(angle = 120deg, length = 50, tag = $seg01)
  |> angledLine(angle = segAng(seg01) + 120deg, length = 50)
  |> line(end = profileStart(%))
  |> close()
  |> extrude(length = 20)

```

--------------------------------

### Example 200 OK Response for Get a personal OAuth app

Source: https://zoo.dev/docs/developer-tools/api/users/get-a-personal-oauth-app?lang=rust

This is an example of a successful response when retrieving a user's OAuth app. It includes details about the app's configuration and status.

```json
{
  "client_id": "b42820eb-598d-47a9-82bc-ca79e2501ce0",
  "client_type": "public",
  "created_at": "2026-05-06T12:35:08.943Z",
  "first_party": false,
  "grant_types": [
    "client_credentials"
  ],
  "is_active": true,
  "mode": "development",
  "name": "CSgN9ue",
  "redirect_uris": [
    "https://DzAW.VxPVNoFC.com/qA/ZjrVo9a"
  ],
  "updated_at": "2026-05-06T12:35:08.943Z"
}

```

--------------------------------

### Example response for Get an org OAuth app

Source: https://zoo.dev/docs/developer-tools/api/orgs/get-an-org-oauth-app

This is an example of a successful response when retrieving an organization's OAuth app. It includes details such as client ID, creation date, and redirect URIs.

```json
{
  "client_id": "28daa88f-fd3e-4ee6-8db8-89be795c21cd",
  "client_type": "confidential",
  "created_at": "2026-05-06T12:26:48.083Z",
  "first_party": true,
  "grant_types": [
    "authorization_code"
  ],
  "is_active": false,
  "mode": "development",
  "name": "",
  "redirect_uris": [
    "https://.Co4Lu2z.com/g2x3H/"
  ],
  "updated_at": "2026-05-06T12:26:48.083Z"
}
```

--------------------------------

### Use Helper Function for Start Point in KCL

Source: https://zoo.dev/docs/kcl-book/sketch2d.html

Employ a helper function like `profileStart()` to retrieve the sketch's starting point. This approach also promotes DRY principles and makes the code more maintainable.

```kcl
startSketchOn(XY)
  |> startProfile(at = [0, 0])
  |> line(end = [3, 0])
  |> line(end = [0, 4])
  |> line(endAbsolute = profileStart())
  |> close()
```

--------------------------------

### Example Usage of faceOf

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-faceOf

Demonstrates how to use the faceOf function to get a specific face from an extruded triangle.

```APIDOC
## Example 1: Extracting a Side Face

### Description
This example shows how to create an extruded triangle and then extract its side face using the `faceOf` function.

### Code
```kcl
triangle = startSketchOn(XY)
  |> startProfile(at = [0, 0])
  |> line(end = [2, 0])
  |> line(end = [0, 2], tag = $side)
  |> line(end = [-2, -2])
  |> close()
  |> extrude(length = 2)

// Get the face of the triangle's side face.
sideFace = faceOf(triangle, face = side)

// Create a new sketch, on the triangle's side face.
// sketch(on = sideFace) {}
```
```

--------------------------------

### TypeScript Setup

Source: https://zoo.dev/docs/developer-tools/api?lang=typescript

Instructions for setting up the official TypeScript client library for Zoo API.

```APIDOC
##### Official clients

```bash
$ npm install @kittycad/lib
```
```

--------------------------------

### Example response for Get an org OAuth app

Source: https://zoo.dev/docs/developer-tools/api/oauth2/get-an-org-oauth-app?lang=curl

This is an example of a successful response when retrieving an organization's OAuth app. It includes details such as client ID, type, creation date, and associated redirect URIs.

```json
{
  "client_id": "f7aeaf29-29fa-42e4-9404-0284fa4dccc3",
  "client_type": "confidential",
  "created_at": "2026-05-06T12:26:15.160Z",
  "first_party": false,
  "grant_types": [
    "authorization_code"
  ],
  "is_active": true,
  "mode": "development",
  "name": "cpP74nzNgP0HAN3s2bZAg",
  "redirect_uris": [
    "https://l3BqS2ZeQcLC.SqJBstrsKKW.com/uYs3t7Lv/za"
  ],
  "updated_at": "2026-05-06T12:26:15.160Z"
}
```

--------------------------------

### Example: Create a Circle and Extrude it

Source: https://zoo.dev/docs/kcl-std/functions/std-solver-circle

This example demonstrates creating a construction circle within a sketch and then extruding a profile defined by that sketch to form a solid. Ensure all sketch elements are properly defined and constrained.

```kcl
profile = sketch(on = XY) {
  circle1 = circle(start = [var 2mm, var 0mm], center = [var 0mm, var 0mm], construction = true)
  edge1 = line(start = [var -3mm, var -2mm], end = [var 3mm, var -2mm])
  edge2 = line(start = [var 3mm, var -2mm], end = [var 3mm, var 2mm])
  edge3 = line(start = [var 3mm, var 2mm], end = [var -3mm, var 2mm])
  edge4 = line(start = [var -3mm, var 2mm], end = [var -3mm, var -2mm])
  coincident([edge1.end, edge2.start])
  coincident([edge2.end, edge3.start])
  coincident([edge3.end, edge4.start])
  coincident([edge4.end, edge1.start])
}

solid = extrude(region(point = [0mm, 0mm], sketch = profile), length = 2)
```

--------------------------------

### Example Project Response

Source: https://zoo.dev/docs/developer-tools/api/projects/list-the-authenticated-user%27s-projects?lang=rust

This is an example of the JSON response when successfully listing the authenticated user's projects. It includes details for a single project.

```json
[
  {
    "category_ids": [
      "2e767393-4449-467a-b0d9-e9f36912e739"
    ],
    "created_at": "2026-05-06T12:33:59.414Z",
    "description": "SDn0e6A3KEYOaVLZ",
    "entrypoint_path": "GRn5LeuPgO4aK0XKahHYcessOW",
    "id": "baaa8f4c-939c-438a-8452-4ac928220b96",
    "preview_status": "ready",
    "preview_url": "ODmjgZAP394",
    "project_toml_path": "3xNf3uY86rfLl1BzbIk1E0Se8g82tU",
    "publication": {
      "has_unpublished_changes": true,
      "last_published_at": "2026-05-06T12:33:59.415Z",
      "last_published_version_id": "7c4b0f33-5eff-4fd7-b95c-dc277bb7d882",
      "submitted_at": "2026-05-06T12:33:59.415Z"
    },
    "publication_status": "pending_review",
    "title": "sbdF1UOJmsZwiWX0WX5xSxLxNVCr",
    "updated_at": "2026-05-06T12:33:59.415Z"
  }
]

```

--------------------------------

### Get the subscription for a user

Source: https://zoo.dev/docs/developer-tools/api/payments/get-the-subscription-for-a-user?lang=curl

This example shows how to retrieve the subscription details for the authenticated user using a cURL command.

```APIDOC
## Get the subscription for a user

### Description
Retrieves the current subscription details for the authenticated user.

### Method
GET

### Endpoint
/user/payment/subscriptions

### Request Example
```curl
curl "https://api.zoo.dev/user/payment/subscriptions" \
	--header "Authorization: Bearer $TOKEN"
```

### Response
#### Success Response (200)
Returns a JSON object containing the user's subscription details.

```json
{
  "action_client_secret": "dTjavN7YVfXVwuX4YN904K",
  "action_type": "setup_intent",
  "modeling_app": {
    "annual_discount": 27,
    "billing_mode": "standard",
    "description": "YSTjHfbobn38OLTncsaCaOi",
    "display_name": "W7dNAjkiPd4YS",
    "endpoints_included": [
      "modeling"
    ],
    "features": [
      {
        "info": "3riNXWYFGxftxXjSdocO7gWVqMiZ"
      }
    ],
    "ml_custom_models": true,
    "monthly_pay_as_you_go_api_credits": 12,
    "monthly_pay_as_you_go_api_credits_monetary_value": "93.05",
    "name": "OAGWMx8JEScajHwA4gbDXn9Y2TyRl",
    "pay_as_you_go_api_credit_price": "2.48",
    "price": {
      "interval": "unknown",
      "price": "53.60",
      "type": "per_user"
    },
    "share_links": [
      "password_protected"
    ],
    "support_tier": "premium",
    "training_data_behavior": "default_on",
    "type": {
      "saml_sso": false,
      "type": "organization"
    },
    "zoo_tools_included": [
      "modeling_app"
    ]
  }
}
```
```

--------------------------------

### Example 200 OK Response for Get Org OAuth App

Source: https://zoo.dev/docs/developer-tools/api/oauth2/get-an-org-oauth-app?lang=python

This is an example of a successful response when retrieving an organization's OAuth app details. It includes information such as client ID, creation date, and redirect URIs.

```json
{
  "client_id": "856e92f6-bae0-45af-ae8b-37cde8fac36d",
  "client_type": "public",
  "created_at": "2026-05-06T12:30:52.284Z",
  "first_party": true,
  "grant_types": [
    "client_credentials"
  ],
  "is_active": true,
  "mode": "production",
  "name": "uWbSxT",
  "redirect_uris": [
    "https://.FFt.com/Sq3/6Kh"
  ],
  "updated_at": "2026-05-06T12:30:52.284Z"
}
```

--------------------------------

### Python SDK Client Setup

Source: https://zoo.dev/docs/developer-tools/api/authentication?lang=python

Set up your Python client by providing your API token directly or by loading it from environment variables. The SDK supports both synchronous and asynchronous operations.

```python
# Setup your client with your token
from kittycad import KittyCAD

client = KittyCAD(token="$TOKEN")

# - OR -

# Create a new client with your token parsed from the environment variable:
# `KITTYCAD_API_TOKEN` or `ZOO_API_TOKEN`.
# Optionally, you can pass in `ZOO_HOST` to specify the host. But this only
# works if you are using the `ZOO_API_TOKEN` environment variable.
from kittycad import KittyCAD

client = KittyCAD()

# NOTE: The python library additionally implements asyncio, however all the code samples we
# show below use the sync functions for ease of use and understanding.
# Check out the library docs at:
# https://python.api.docs.zoo.dev
# for more details.
```

--------------------------------

### Set up Virtual Environment and Activate

Source: https://zoo.dev/docs/developer-tools/tutorials/websocket-tutorial

Create and activate a Python virtual environment to isolate project dependencies. This ensures that libraries installed for this project do not conflict with system-wide Python packages.

```bash
pip3 install virtualenv
python3 -m venv venv
source venv/bin/activate

```

--------------------------------

### Create and Extrude Profile on Negative XZ Plane

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-startProfile

Illustrates creating a sketch on the negative XZ plane, starting a profile at [10, 10], and then forming a square and extruding it. This example highlights starting a profile at a non-origin point.

```kcl
exampleSketch = startSketchOn(-XZ)
  |> startProfile(at = [10, 10])
  |> line(end = [10, 0])
  |> line(end = [0, 10])
  |> line(end = [-10, 0])
  |> close()

example = extrude(exampleSketch, length = 5)
```

--------------------------------

### Create Subscription

Source: https://zoo.dev/docs/developer-tools/api/payments/create-the-subscription-for-a-user?lang=curl

This example demonstrates how to create a subscription for a user via a POST request to the /user/payment/subscriptions endpoint.

```APIDOC
## POST /user/payment/subscriptions

### Description
Creates a subscription for the authenticated user.

### Method
POST

### Endpoint
/user/payment/subscriptions

### Request Body
- **modeling_app** (string) - Required - The ID of the modeling app to subscribe to.
- **pay_annually** (boolean) - Optional - If true, the subscription will be billed annually.

### Request Example
```json
{
  "modeling_app": "8YUyr4rOrqiu02ViRjO0tBCtrgVVj",
  "pay_annually": true
}
```

### Response
#### Success Response (201 Created)
- **action_client_secret** (string) - The client secret for the payment action.
- **action_type** (string) - The type of action, e.g., 'payment_intent'.
- **modeling_app** (object) - Details about the subscribed modeling app.
  - **annual_discount** (number) - The annual discount percentage.
  - **billing_mode** (string) - The billing mode (e.g., 'contract').
  - **description** (string) - A description of the modeling app.
  - **display_name** (string) - The display name of the modeling app.
  - **endpoints_included** (array) - A list of included endpoints.
  - **features** (array) - A list of features included in the subscription.
  - **ml_custom_models** (boolean) - Whether custom ML models are included.
  - **monthly_pay_as_you_go_api_credits** (number) - Included API credits per month.
  - **monthly_pay_as_you_go_api_credits_monetary_value** (string) - The monetary value of the monthly API credits.
  - **name** (string) - The internal name of the modeling app.
  - **pay_as_you_go_api_credit_price** (string) - The price per API credit for pay-as-you-go.
  - **price** (object) - Pricing details.
    - **type** (string) - The type of pricing (e.g., 'contract').
  - **share_links** (array) - Options for sharable links.
  - **support_tier** (string) - The support tier provided.
  - **training_data_behavior** (string) - The behavior of user data for training.
  - **type** (object) - The type of subscription tier.
    - **type** (string) - The specific type (e.g., 'individual').
  - **zoo_tools_included** (array) - A list of included Zoo tools.

### Response Example
```json
{
  "action_client_secret": "Awp6jU",
  "action_type": "payment_intent",
  "modeling_app": {
    "annual_discount": 30,
    "billing_mode": "contract",
    "description": "M1FA2ibLyciaAznMlOuS6G7e",
    "display_name": "1Rd4QBS8qCob7co1NPqLSw5",
    "endpoints_included": [
      "ml"
    ],
    "features": [
      {
        "info": "FzYQOLsGyE2KKZBOKjS1Jcb1Tvvv06cifZFdUKs7sQNymouFKyqvOoX2y0bQtzpeM"
      }
    ],
    "ml_custom_models": true,
    "monthly_pay_as_you_go_api_credits": 30,
    "monthly_pay_as_you_go_api_credits_monetary_value": "98.16",
    "name": "E1coqNZBPBm7cs5KaQKK",
    "pay_as_you_go_api_credit_price": "57.76",
    "price": {
      "type": "contract"
    },
    "share_links": [
      "public"
    ],
    "support_tier": "priority_email",
    "training_data_behavior": "default_on",
    "type": {
      "type": "individual"
    },
    "zoo_tools_included": [
      "text_to_cad"
    ]
  }
}
```
```

--------------------------------

### Circle with Tangent Angled Line Example

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-tangentToEnd

This example shows how to create a triangle shape adjacent to a circle, where one side of the triangle is an angled line tangent to the circle. The tangentToEnd function is used to get the tangent angle from the circle.

```kcl
circSketch = startSketchOn(XY)
  |> circle(center = [0, 0], radius = 3, tag = $circ)

triangleSketch = startSketchOn(XY)
  |> startProfile(at = [-5, 0])
  |> angledLine(angle = tangentToEnd(circ), length = 10)
  |> line(end = [-15, 0])
  |> close()


```

--------------------------------

### Get shortlinks for an org (TypeScript)

Source: https://zoo.dev/docs/developer-tools/api/orgs/get-the-shortlinks-for-an-org

This TypeScript example uses the 'fetch' API to get shortlinks for an organization. Remember to replace the placeholder token and parameter values with your actual data. This code is suitable for environments where the Fetch API is available.

```typescript
async function getOrgShortlinks() {
  const token = "$TOKEN";
  const limit = "VALUE";
  const page_token = "VALUE";
  const sort_by = "VALUE";

  const response = await fetch(
    `https://api.zoo.dev/org/shortlinks?limit=${limit}&page_token=${page_token}&sort_by=${sort_by}`,
    {
      method: "GET",
      headers: {
        "Authorization": `Bearer ${token}`,
        "Content-Type": "application/json"
      }
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const data = await response.json();
  console.log(data);
}

getOrgShortlinks();
```

--------------------------------

### Project Response Example

Source: https://zoo.dev/docs/developer-tools/api/projects/get-one-of-the-authenticated-user%27s-projects?lang=rust

This is an example of a successful response when retrieving a project. It includes details such as IDs, timestamps, file information, and publication status.

```json
{
  "category_ids": [
    "dca95175-fc79-454b-8437-b0a6245a82a5"
  ],
  "created_at": "2026-05-06T12:33:47.892Z",
  "description": "Ymp7v8F1RxaQIFQWWPKcHVYJ",
  "entrypoint_path": "yQT",
  "files": [
    {
      "byte_size": 2,
      "content_type": "V2VGxSP38zxzkareHZ04FXeq",
      "created_at": "2026-05-06T12:33:47.892Z",
      "file_role": "project_file",
      "id": "cc32ddb8-c281-4c31-aac0-dd5baf24cd5f",
      "relative_path": "GrNaV5b205gcx",
      "sha256": "6am",
      "sort_order": 4,
      "updated_at": "2026-05-06T12:33:47.892Z"
    }
  ],
  "id": "0766f89c-c5b9-4c62-81b1-a026a71040bd",
  "preview_status": "ready",
  "preview_url": "",
  "project_toml_path": "BamZ2aYiLqTZ5PD5wUFrsh2alnHT",
  "publication": {
    "has_unpublished_changes": false,
    "last_published_at": "2026-05-06T12:33:47.892Z",
    "last_published_version_id": "598dc69f-cf28-49d6-b32d-b5ddefa4d1f5",
    "submitted_at": "2026-05-06T12:33:47.892Z"
  },
  "publication_status": "pending_review",
  "title": "pRJIq1WcDh54cm9wG1T0",
  "updated_at": "2026-05-06T12:33:47.892Z"
}

```

--------------------------------

### User Configuration Structure Example

Source: https://zoo.dev/docs/kcl-lang/settings/user

Defines user-specific application and modeling settings. Do not edit this file manually as it may be overwritten or corrupted.

```toml
[settings.app]
# Set the appearance of the application
[settings.app.appearance]
# Use dark mode theme
theme = "dark"
# Set the app color to blue (240.0 = blue, 0.0 = red, 120.0 = green)
color = 240.0

[settings.modeling]
# Use millimeters as the default measurement unit
base_unit = "mm"


```

--------------------------------

### Example Usage of conic Function

Source: https://zoo.dev/docs/kcl-std/functions/std-sketch-conic

Demonstrates how to use the conic function to add a conic section to a sketch. This example uses relative end and interior points, along with explicit start and end tangents. Ensure experimental features are enabled.

```kcl
@settings(experimentalFeatures = allow)

exampleSketch = startSketchOn(XZ)
  |> startProfile(at = [0, 0])
  |> conic(
       end = [20, 0],
       endTangent = [1, 1],
       interior = [5, 5],
       startTangent = [0, -1],
     )
  |> close()
example = extrude(exampleSketch, length = 10)

```

--------------------------------

### Example Project Response

Source: https://zoo.dev/docs/developer-tools/api/projects/list-the-authenticated-user%27s-projects?lang=typescript

This is an example of a successful response when listing projects. It shows the structure and data fields returned for each project.

```json
[
  {
    "category_ids": [
      "80e45cdd-bde3-4a1b-a779-5a1b594d5486"
    ],
    "created_at": "2026-05-06T12:33:59.435Z",
    "description": "8VA",
    "entrypoint_path": "YMNhe",
    "id": "13118303-f117-47e4-9a6f-964e98d2c477",
    "preview_status": "ready",
    "preview_url": "x",
    "project_toml_path": "Ripd8rrNTi8UehtladafhXjkVsz",
    "publication": {
      "has_unpublished_changes": true,
      "last_published_at": "2026-05-06T12:33:59.435Z",
      "last_published_version_id": "eefa249a-3535-41f5-89ec-bacac3874dc1",
      "submitted_at": "2026-05-06T12:33:59.435Z"
    },
    "publication_status": "deleted",
    "title": "0xy19EEZlSRGZNQvROfZig1nQktHr",
    "updated_at": "2026-05-06T12:33:59.435Z"
  }
]
```

--------------------------------

### Successful response for Get an org

Source: https://zoo.dev/docs/developer-tools/api/orgs/get-an-org

This is an example of a successful JSON response when retrieving organization details. It includes various properties of the organization.

```json
{
  "allow_users_in_domain_to_auto_join": false,
  "aws_external_id": "40fe8082-4b5c-4856-96cb-a110dc438a4b",
  "billing_email": "jknsTA@ilKvvThiBz.com",
  "billing_email_verified": "2026-05-06T12:26:47.707Z",
  "block": "upgrade_downgrade_abuse",
  "can_train_on_data": true,
  "created_at": "2026-05-06T12:26:47.707Z",
  "domain": "I",
  "id": "99fdc3f3-b72f-42d5-a118-d1705c9c9c9a",
  "image": "https://w36HMU8Kd.Cg.com/7iYu5dk75QtN/CCdW7rXw80",
  "name": "QDRoLvCDI",
  "phone": "+1-836-360-9048",
  "stripe_id": "kqNm9oDV",
  "updated_at": "2026-05-06T12:26:47.707Z"
}
```

--------------------------------

### Python SDK Example for File Conversion

Source: https://zoo.dev/docs/developer-tools/api/file/convert-cad-file-with-defaults?lang=python

This snippet demonstrates how to use the KittyCAD Python SDK to convert a file from one format to another using default options. It shows the creation of a client, the call to the `create_file_conversion` method, and how to access the result.

```APIDOC
## POST /file/conversion/{src_format}/{output_format}

### Description
Converts a CAD file from a source format to an output format. This endpoint can be used to convert files with default options.

### Method
POST

### Endpoint
`/file/conversion/{src_format}/{output_format}`

### Parameters
#### Path Parameters
- **src_format** (FileImportFormat) - Required - The source format of the file to be converted.
- **output_format** (FileExportFormat) - Required - The desired output format for the converted file.

#### Request Body
- **body** (bytes) - Required - The content of the file to be converted.

### Request Example
```python
from kittycad.models.file_import_format import FileImportFormat
from kittycad.models.file_export_format import FileExportFormat
from kittycad.models import FileConversion
from kittycad.client import KittyCAD

client = KittyCAD()

result: FileConversion = client.file.create_file_conversion(
    src_format=FileImportFormat.FBX,
    output_format=FileExportFormat.FBX,
    body=bytes('some bytes', 'utf-8')
)

body: FileConversion = result
print(body)
```

### Response
#### Success Response (201 Created)
- **id** (string) - The unique identifier for the conversion job.
- **src_format** (string) - The source format of the input file.
- **output_format** (string) - The desired output format.
- **status** (string) - The current status of the conversion job (e.g., 'queued', 'in_progress', 'completed', 'failed').
- **created_at** (string) - The timestamp when the conversion job was created.
- **updated_at** (string) - The timestamp when the conversion job was last updated.
- **completed_at** (string) - The timestamp when the conversion job was completed.
- **error** (string) - Any error message if the conversion failed.
- **user_id** (string) - The ID of the user who initiated the conversion.
- **src_format_options** (object) - Options specific to the source format.
- **output_format_options** (object) - Options specific to the output format.
- **outputs** (object) - Information about the output files.

#### Response Example
```json
{
  "completed_at": "2026-05-06T12:29:56.981Z",
  "created_at": "2026-05-06T12:29:56.982Z",
  "error": "",
  "id": "1dc58ace-9826-4a4f-95ec-01b92b0ce147",
  "output_format": "obj",
  "output_format_options": {
    "coords": {
      "forward": {
        "axis": "y",
        "direction": "negative"
      },
      "up": {
        "axis": "z",
        "direction": "negative"
      }
    },
    "created": "2026-05-06T12:29:56.982Z",
    "presentation": "compact",
    "type": "step",
    "units": "yd"
  },
  "outputs": {},
  "src_format": "step",
  "src_format_options": {
    "coords": {
      "forward": {
        "axis": "z",
        "direction": "positive"
      },
      "up": {
        "axis": "z",
        "direction": "positive"
      }
    },
    "type": "obj",
    "units": "yd"
  },
  "started_at": "2026-05-06T12:29:56.982Z",
  "status": "completed",
  "updated_at": "2026-05-06T12:29:56.982Z",
  "user_id": "b334abbc-b446-4c77-9633-8c21b0e71157"
}
```
```
Tokens:
Raw