> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gizmo.antimlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Edit collisions

> Change an existing asset's colliders using a natural-language instruction.

Available with **Team keys** on releases with collision editing enabled.

## Submit an edit

```bash theme={null}
curl --fail-with-body -X POST \
  "https://api.gizmo.antimlabs.com/v1/assets/ASSET_ID/collision-edits" \
  -H "Authorization: Bearer $GIZMO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: collision-edit-001" \
  -d '{"instruction": "Simplify the handle colliders while preserving the grip surface."}'
```

`instruction` is required and accepts 1–20,000 characters of nonempty text.
Use a new idempotency key for each intended edit; reuse the same key and request
when retrying a submission after a connection error.

The source must be a completed asset in the same Team with retained native
authoring and existing convex colliders; a visual-only upload is insufficient.
The key needs `generate:asset` and `export:assets` access.

## Retrieve the edited asset

The response is `202 Accepted` with `job_id`; poll
`GET /v1/jobs/{job_id}?include_result=true` as for normal generation.
On success, `result.asset.id` identifies a **new asset** containing the edits;
the source asset and its downloads remain available.

Edits start from the existing colliders and preserve visual geometry, materials,
body ownership and articulation; geometry outside the selected edit scope is
protected, and the resulting collision GLB, physics metadata and native exports
are regenerated consistently from the edited candidate.

Download the new asset's `glb_bundle` to obtain `visual.glb`, `collision.glb` and
`physics.json`, or request its USD export using the existing download endpoints.
The new asset records its source asset ID and instruction in
`metadata.collisionEdit`.

Collision edits use the existing Team job queue, billing and cancellation flow.
An incompatible release returns `409 collision_edit_unavailable`;
source assets without an editable retained package cannot be edited in place.
An edit does not fall back to regenerating the whole collision mesh.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.