> For the complete documentation index, see [llms.txt](https://docs.projectsim.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.projectsim.ai/api-reference/settings.md).

# Settings

## Get settings

> Retrieve your default parameters, fully resolved.\
> \
> These are the defaults that request \`params\` merge over on every\
> create call. The response is the complete resolved object,\
> including values you have never set explicitly.

```json
{"openapi":"3.1.0","info":{"title":"projectsim API","version":"1.0.0-beta"},"security":[{"ProjectSimToken":[]}],"components":{"securitySchemes":{"ProjectSimToken":{"bearerFormat":"kps_live_...","description":"A per-user API token. The tenant is the user, so no request body carries a user id. Tokens without the `kps_` prefix are rejected before any lookup.","scheme":"bearer","type":"http"}},"schemas":{"Params":{"additionalProperties":false,"properties":{"mesh":{"$ref":"#/components/schemas/MeshParams","default":{"quality":"standard"}},"physics":{"$ref":"#/components/schemas/PhysicsParams","default":{"body":"rigid","collision":"auto","simulator":"isaac_sim_physx"}},"texture":{"$ref":"#/components/schemas/TextureParams","default":{"resolution":4096}},"variation":{"$ref":"#/components/schemas/VariationParams","default":{"variation_type":"general","wildness":"moderate"}}},"title":"Params","type":"object"},"MeshParams":{"additionalProperties":false,"properties":{"quality":{"default":"standard","enum":["standard","low","ultra_low"],"title":"Quality","type":"string"}},"title":"MeshParams","type":"object"},"PhysicsParams":{"additionalProperties":false,"properties":{"body":{"default":"rigid","description":"Physical behavior of the bodies: rigid preserves shape; deformable uses soft-body simulation.","enum":["rigid","deformable"],"title":"Body","type":"string"},"collision":{"default":"auto","enum":["auto","convex_hull","convex_decomposition","coacd","bounding_box","sdf"],"title":"Collision","type":"string"},"simulator":{"default":"isaac_sim_physx","description":"Target runtime. Native formats and physics engine are derived internally; agnostic delivers FBX and GLB plus physics sidecar.","enum":["isaac_sim_physx","isaac_sim_newton","mujoco","sapien","genesis","agnostic"],"title":"Simulator","type":"string"}},"title":"PhysicsParams","type":"object"},"TextureParams":{"additionalProperties":false,"properties":{"resolution":{"default":4096,"enum":[1024,2048,4096,8192],"title":"Resolution","type":"integer"}},"title":"TextureParams","type":"object"},"VariationParams":{"additionalProperties":false,"description":"How an image-method set's variants are generated. Ignored otherwise.\n\nA deliberate subset of the generator's options: what a customer steers,\nnot how many images it makes. Count is the set's `count`, one image per\nmember, so it is not reachable from here. The generator's custom prompt\nis not steered here either — it comes from the set's `seed.text` — and\nthe subject name comes from the set's `name`.","properties":{"variation_type":{"default":"general","enum":["texture","general"],"title":"Variation Type","type":"string"},"wildness":{"default":"moderate","enum":["subtle","moderate","bold","wild"],"title":"Wildness","type":"string"}},"title":"VariationParams","type":"object"},"Problem":{"description":"An RFC 7807 error, the shape every failure uses.\n\nDeclared explicitly because the handlers replace FastAPI's default\nvalidation response; without this the spec would advertise\n`HTTPValidationError`, whose `detail` is a list rather than a string,\nand every generated client would crash parsing a 422.","properties":{"detail":{"description":"Human-readable explanation of this occurrence.","title":"Detail","type":"string"},"errors":{"anyOf":[{"items":{"$ref":"#/components/schemas/ValidationDetail"},"type":"array"},{"type":"null"}],"description":"Present on a 422; one entry per failing field.","title":"Errors"},"instance":{"description":"Identifies this occurrence; quote it to support.","title":"Instance","type":"string"},"path":{"title":"Path","type":"string"},"request_id":{"description":"Also returned in the X-Request-Id response header.","title":"Request Id","type":"string"},"status":{"title":"Status","type":"integer"},"title":{"title":"Title","type":"string"},"type":{"description":"Stable URI identifying the error class.","title":"Type","type":"string"}},"required":["type","title","status","detail","instance","path","request_id"],"title":"Problem","type":"object"},"ValidationDetail":{"description":"One field-level validation failure.","properties":{"loc":{"description":"Dotted path to the offending field.","title":"Loc","type":"string"},"msg":{"title":"Msg","type":"string"},"type":{"title":"Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationDetail","type":"object"}}},"paths":{"/v1/settings":{"get":{"description":"Retrieve your default parameters, fully resolved.\n\nThese are the defaults that request `params` merge over on every\ncreate call. The response is the complete resolved object,\nincluding values you have never set explicitly.","operationId":"get_settings","responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Params"}}},"description":"Successful Response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid API token"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Request body too large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Request failed validation"}},"summary":"Get settings","tags":["settings"]}}}}
```

## Update Settings

> Update your default parameters.\
> \
> A partial patch: only the fields you send change, and nested\
> objects deep-merge rather than being replaced wholesale. The\
> response is the full resolved result.\
> \
> Invalid combinations are rejected with \`422\` and nothing is\
> saved. New defaults apply to later creates only — work already\
> under way keeps the \`effective\_params\` frozen at its creation.

```json
{"openapi":"3.1.0","info":{"title":"projectsim API","version":"1.0.0-beta"},"security":[{"ProjectSimToken":[]}],"components":{"securitySchemes":{"ProjectSimToken":{"bearerFormat":"kps_live_...","description":"A per-user API token. The tenant is the user, so no request body carries a user id. Tokens without the `kps_` prefix are rejected before any lookup.","scheme":"bearer","type":"http"}},"schemas":{"Params":{"additionalProperties":false,"properties":{"mesh":{"$ref":"#/components/schemas/MeshParams","default":{"quality":"standard"}},"physics":{"$ref":"#/components/schemas/PhysicsParams","default":{"body":"rigid","collision":"auto","simulator":"isaac_sim_physx"}},"texture":{"$ref":"#/components/schemas/TextureParams","default":{"resolution":4096}},"variation":{"$ref":"#/components/schemas/VariationParams","default":{"variation_type":"general","wildness":"moderate"}}},"title":"Params","type":"object"},"MeshParams":{"additionalProperties":false,"properties":{"quality":{"default":"standard","enum":["standard","low","ultra_low"],"title":"Quality","type":"string"}},"title":"MeshParams","type":"object"},"PhysicsParams":{"additionalProperties":false,"properties":{"body":{"default":"rigid","description":"Physical behavior of the bodies: rigid preserves shape; deformable uses soft-body simulation.","enum":["rigid","deformable"],"title":"Body","type":"string"},"collision":{"default":"auto","enum":["auto","convex_hull","convex_decomposition","coacd","bounding_box","sdf"],"title":"Collision","type":"string"},"simulator":{"default":"isaac_sim_physx","description":"Target runtime. Native formats and physics engine are derived internally; agnostic delivers FBX and GLB plus physics sidecar.","enum":["isaac_sim_physx","isaac_sim_newton","mujoco","sapien","genesis","agnostic"],"title":"Simulator","type":"string"}},"title":"PhysicsParams","type":"object"},"TextureParams":{"additionalProperties":false,"properties":{"resolution":{"default":4096,"enum":[1024,2048,4096,8192],"title":"Resolution","type":"integer"}},"title":"TextureParams","type":"object"},"VariationParams":{"additionalProperties":false,"description":"How an image-method set's variants are generated. Ignored otherwise.\n\nA deliberate subset of the generator's options: what a customer steers,\nnot how many images it makes. Count is the set's `count`, one image per\nmember, so it is not reachable from here. The generator's custom prompt\nis not steered here either — it comes from the set's `seed.text` — and\nthe subject name comes from the set's `name`.","properties":{"variation_type":{"default":"general","enum":["texture","general"],"title":"Variation Type","type":"string"},"wildness":{"default":"moderate","enum":["subtle","moderate","bold","wild"],"title":"Wildness","type":"string"}},"title":"VariationParams","type":"object"},"Problem":{"description":"An RFC 7807 error, the shape every failure uses.\n\nDeclared explicitly because the handlers replace FastAPI's default\nvalidation response; without this the spec would advertise\n`HTTPValidationError`, whose `detail` is a list rather than a string,\nand every generated client would crash parsing a 422.","properties":{"detail":{"description":"Human-readable explanation of this occurrence.","title":"Detail","type":"string"},"errors":{"anyOf":[{"items":{"$ref":"#/components/schemas/ValidationDetail"},"type":"array"},{"type":"null"}],"description":"Present on a 422; one entry per failing field.","title":"Errors"},"instance":{"description":"Identifies this occurrence; quote it to support.","title":"Instance","type":"string"},"path":{"title":"Path","type":"string"},"request_id":{"description":"Also returned in the X-Request-Id response header.","title":"Request Id","type":"string"},"status":{"title":"Status","type":"integer"},"title":{"title":"Title","type":"string"},"type":{"description":"Stable URI identifying the error class.","title":"Type","type":"string"}},"required":["type","title","status","detail","instance","path","request_id"],"title":"Problem","type":"object"},"ValidationDetail":{"description":"One field-level validation failure.","properties":{"loc":{"description":"Dotted path to the offending field.","title":"Loc","type":"string"},"msg":{"title":"Msg","type":"string"},"type":{"title":"Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationDetail","type":"object"}}},"paths":{"/v1/settings":{"patch":{"description":"Update your default parameters.\n\nA partial patch: only the fields you send change, and nested\nobjects deep-merge rather than being replaced wholesale. The\nresponse is the full resolved result.\n\nInvalid combinations are rejected with `422` and nothing is\nsaved. New defaults apply to later creates only — work already\nunder way keeps the `effective_params` frozen at its creation.","operationId":"update_settings","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Params"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Params"}}},"description":"Successful Response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Missing or invalid API token"},"413":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Request body too large"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}},"description":"Request failed validation"}},"summary":"Update Settings","tags":["settings"]}}}}
```