# krad — 3D CAD API

> krad is a browser-based 3D CAD tool with a programmatic REST + WebSocket API.
> Any authenticated client can create 3D geometry, manipulate it, and export STL/GLB/OBJ/PLY files.

## Authentication

1. Create an account at https://krad.app/signup
2. Create an API token at https://krad.app/user#api (Settings → API tab)
3. Token format: krad_<hex>
4. Send as: Authorization: Bearer krad_<your_token>

## Quick Start

```bash
# If the user gives you a project ID, use it directly — DON'T call create!
# Just send commands to /api/scene/PROJECT_ID/command.
# Only call create when you need a brand new blank project:
curl -X POST https://krad.app/api/scene/create \
  -H "Authorization: Bearer krad_YOUR_TOKEN"
# Returns: {"project_id": "..."}

# Add shapes and manipulate them (use existing project ID or one from create)
curl -X POST https://krad.app/api/scene/PROJECT_ID/command \
  -H "Authorization: Bearer krad_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"commands": [
    {"type": "add_box", "width": 3, "height": 2, "depth": 1},
    {"type": "add_sphere", "radius": 0.5},
    {"type": "set_position", "id": 2, "x": 2, "y": 0.5, "z": 0},
    {"type": "set_color", "id": 1, "r": 0.8, "g": 0.2, "b": 0.1}
  ]}'

# Query scene state
curl https://krad.app/api/scene/PROJECT_ID/state \
  -H "Authorization: Bearer krad_YOUR_TOKEN"

# Export as STL
curl https://krad.app/api/scene/PROJECT_ID/export/stl \
  -H "Authorization: Bearer krad_YOUR_TOKEN" -o scene.stl

# Export as GLB (with textures)
curl https://krad.app/api/scene/PROJECT_ID/export/glb \
  -H "Authorization: Bearer krad_YOUR_TOKEN" -o scene.glb
```

## WebSocket

Connect for real-time bidirectional control:
```
ws://https://krad.app/api/scene/PROJECT_ID/ws?token=krad_YOUR_TOKEN
```
Send JSON commands, receive JSON events with updated scene state.

## Available Commands

All commands are JSON objects with a "type" field. Send as array in {"commands": [...]}.

### Primitives
- add_box: width, height, depth (f64, default 2.0). Creates a box centered on the ground plane.
- add_sphere: radius (f64, default 1.0)
- add_cylinder: radius (f64, default 1.0), height (f64, default 2.0)
- add_cone: radius, height (f64)
- add_torus: major_radius (f64, default 1.0), minor_radius (f64, default 0.3)
- add_wedge: width, height, depth (f64). Triangular prism — isosceles triangle in XY, swept along Z.

### Selection
- select: id (u64)
- select_by_name: name (string)
- deselect_all

### Transform
- set_position: id, x, y, z (f32). Moves object to absolute position.
- set_rotation: id, x, y, z (f32). Sets Euler rotation in radians (applied as Y→X→Z).
- set_scale: id, x, y, z (f32). Uniform scale (values averaged).
- set_color: id, r, g, b (f32, 0.0-1.0)
- rename: id, name (string)

### Boolean Operations
- boolean_union: a, b (u64 object IDs). Merges two objects into one.
- boolean_subtract: a, b (u64). Subtracts object b from object a.
- boolean_intersect: a, b (u64). Keeps only the overlapping volume.

Note: booleans create a new result object and hide the source objects. The result gets the next available ID. CSG evaluation runs server-side — the result object will have `has_mesh: true` and `vertex_count`/`triangle_count` immediately. Check the response "objects" array for the new state.

### Sketch + Extrude (Compound)
- extrude_box: x, z (f32 center), width, depth (f32), height (f64). Draws a rectangle on the ground plane and extrudes it vertically. Creates a solid box from a sketch profile — more flexible than add_box for CAD workflows.
- extrude_cylinder: x, z (f32 center), radius (f32), height (f64). Draws a circle and extrudes it.

### Operations
- delete: id (u64)
- delete_selected

### Camera
- set_view: angle (string). Values: front, back, left, right, top, bottom.
- zoom_to_fit

### Units
- set_unit: unit (string). Values: mm, cm, m, in, ft. Affects export dimensions.

### Save & Export
- save_project: name (string). Saves the scene as a cloud project visible at /projects. Returns project_id in the effects. The project can then be opened in the browser editor, shared, forked, etc. Call this when the design is ready.
- export_stl: returns STL binary in the response effects
- export_glb: returns GLB binary (with textures if present)

### AI Operations
- ai_segment: image_b64 OR upload_id, prompt (string, optional — e.g. "the red cup"). Segments objects in an image using AI. Returns masks as base64 PNGs and a cutout image. Rate limited per tier.
- ai_generate_3d: image_b64 OR upload_id, name (string, optional). **Async**: returns a job_id immediately. Poll GET /api/scene/{id}/jobs/{job_id} for status. When complete, the mesh is auto-imported into the scene and the response includes the updated objects array. Takes 30-120 seconds of GPU time. Rate limited per tier.

Note: AI operations accept images via inline base64 (image_b64) or by reference (upload_id from POST /api/scene/{id}/upload). Upload is recommended for large images — avoids the ~33% base64 bloat in JSON.

To upload: POST raw image bytes to /api/scene/{id}/upload (Content-Type: image/jpeg or application/octet-stream). Returns {"upload_id": "..."}. Then use that upload_id in ai_generate_3d or ai_segment.

### Project Management
- load_project: project_id (UUID string). Loads a saved cloud project into this session, replacing current scene state. Objects and meshes are restored. Use this to resume work from a previous save_project.

## Tips for AI Agents

1. **If the user gives you a project ID, use it directly as the session ID in all endpoints** (/command, /upload, /export/stl, etc.). Do NOT call /api/scene/create — that creates a separate project. Scene state loads automatically from the saved snapshot. Only call create when you need a brand new blank project and the user hasn't given you a project ID.
2. After each command batch, the response includes the full "objects" array with IDs, names, positions, colors, has_mesh, vertex_count, and triangle_count. Use `has_mesh: true` to confirm geometry is ready for export.
3. Boolean operations work immediately — CSG evaluation runs server-side. Both source objects must have meshes (primitives get meshed automatically when added). The result object will have `has_mesh: true` in the response.
4. Object IDs are sequential starting from 1. After a boolean, sources become hidden (visible: false) and the result gets a new ID.
5. The coordinate system is Y-up. The ground plane is Y=0. Objects are placed with their center at Y = half_height by default.
6. STL export converts to Z-up and scales to millimeters based on the set_unit value.
7. **Always save_project after meaningful work.** save_project persists your scene to the cloud (S3 + database). The response includes a project URL the user can open in their browser.
8. **Keep sessions alive during long AI jobs.** ai_generate_3d can take 1-6 minutes (GPU cold start + generation). While polling GET /api/scene/{id}/jobs/{job_id}, also ping GET /api/scene/{id}/state every 30 seconds to keep the session active.

## Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | /api/scene/create | Create session |
| GET | /api/scene/sessions | List your sessions |
| DELETE | /api/scene/sessions | Delete all your sessions |
| POST | /api/scene/{id}/command | Execute commands |
| GET | /api/scene/{id}/state | Query state |
| POST | /api/scene/{id}/upload | Upload image for AI ops |
| GET | /api/scene/{id}/export/stl | Download STL |
| GET | /api/scene/{id}/export/glb | Download GLB |
| GET | /api/scene/{id}/jobs/{job_id} | Poll async job status |
| GET | /api/scene/{id}/ws?token=... | WebSocket |
| DELETE | /api/scene/{id} | Destroy session |

## OpenAPI Spec

Machine-readable spec at: https://krad.app/api/openapi.json

## Limits

- Max 20 concurrent sessions per user
- Sessions expire after 30 minutes of inactivity
- All operations count against your account's tier limits