# Place an Object

Place a catalog asset in an authored world. Supply the current state digest, a unique object ID, a supported region, and an asset digest from the catalog.

## Request and Response

POST `/world/versions/{version_id}/objects`

The edit advances the authored state under the same version ID. Include saved_entry to update the saved entry’s digest and edit cursor together with the edit. A stale base is refused; reread the state before reconciling your change.

### Parameters

`version_id` · path, uuid · required

`world_id` · query, string · required

### Request body

`base_state_sha256` · string · required

The state_sha256 from the version you read. A changed base is refused.

pattern: ^[0-9a-f]{64}$

`saved_entry` · object | null

Update the saved entry’s state digest and edit cursor together with the object edit.

**Show properties**

`entry_id` · uuid · required

`base_revision` · integer · required

minimum: 1

`authored_state_sha256` · string · required

pattern: ^[0-9a-f]{64}$

`authored_edit_seq` · integer · required

minimum: 0

`object_id` · string · required

A unique identifier for the object in this world.

minLength: 1, maxLength: 200

`asset_sha256` · string · required

Content digest of an asset from the server’s catalog.

minLength: 64, maxLength: 64

`region_id` · string · required

A region offered by the version’s capability descriptor.

minLength: 1, maxLength: 500

`transform` · object · required

Position in millimeters, yaw in microradians, and scale in thousandths.

**Show properties**

`x_mm` · integer · required

`y_mm` · integer · required

`z_mm` · integer · required

`yaw_microradians` · integer · required

minimum: 0, maximum: 6283185

`scale_milli` · integer · required

minimum: 1, maximum: 1000000

`origin_role` · "fictional" | "personal" · required

Whether the object is authored fiction or belongs to the personal world.

`behaviour` · object | null

Optional behavior binding supported by this version.

**Show properties**

`behaviour_key` · string · required

maxLength: 200

`behaviour_version` · integer · required

minimum: 1

`parameters` · object · required

### Response

201application/json`schema_version` · integer · required

`version_id` · uuid · required

`world_id` · string · required

`source_snapshot_id` · uuid · required

`parent_version_id` · uuid | null · required

`title` · string · required

The name shown for this saved world.

`origin` · string · required

`style_version_id` · uuid | null · required

`state_sha256` · string · required

`edit_seq` · integer · required

`source_invalidated` · boolean · required

`created_by` · uuid · required

`created_at` · string · required

`objects` · object[] · required

**Show properties**

Array of object values

`object_id` · string · required

`asset` · object | null · required

**Show properties**

`asset_key` · string · required

`title` · string · required

`summary` · string · required

`media_type` · string · required

`content_sha256` · string · required

`byte_size` · integer · required

`licence_id` · string · required

`licence_sha256` · string · required

`availability` · string · required

`placeable` · boolean · required

`workspace_asset` · object | null

**Show properties**

`asset_id` · uuid · required

`preparation_id` · uuid · required

`title` · string · required

`content_sha256` · string · required

`byte_size` · integer · required

`media_type` · string · required

`licence_id` · string | null · required

`attribution` · string | null · required

`availability` · string · required

`region_id` · string · required

`transform` · object · required

**Show properties**

`coordinate_space` · string · required

`coordinate_unit` · string · required

`x_mm` · integer · required

`y_mm` · integer · required

`z_mm` · integer · required

`yaw_microradians` · integer · required

`scale_milli` · integer · required

`origin` · object · required

**Show properties**

`kind` · string · required

`role` · string · required

`behaviour` · object | null · required

**Show properties**

`behaviour_key` · string · required

`behaviour_version` · integer · required

`parameters` · object · required

`removed` · boolean · required

`element_overrides` · object[] · required

**Show properties**

Array of object values

`element_id` · string · required

`suppressed` · boolean · required

`transform` · object | null · required

**Show properties**

`coordinate_space` · string · required

`coordinate_unit` · string · required

`x_mm` · integer · required

`y_mm` · integer · required

`z_mm` · integer · required

`yaw_microradians` · integer · required

`scale_milli` · integer · required

`storeys` · integer | null

`environment_instances` · object[] · required

**Show properties**

Array of object values

An object with properties defined by the server.

`point_map_instances` · object[] · required

**Show properties**

Array of object values

An object with properties defined by the server.

`things` · object[] · required

**Show properties**

Array of object values

An object with properties defined by the server.

`edits` · object[] · required

**Show properties**

Array of object values

`edit_id` · uuid · required

`edit_seq` · integer · required

`kind` · string · required

`object_id` · string | null · required

`element_id` · string | null · required

`environment_instance_id` · string | null · required

`point_map_instance_id` · string | null · required

`thing_id` · string | null · required

`undone_edit_id` · uuid | null · required

`base_state_sha256` · string · required

`result_state_sha256` · string · required

`actor` · uuid · required

`recorded_at` · string · required

`storeys` · object | null

**Show properties**

`before` · integer | null · required

`after` · integer | null · required

`turned_in_place` · boolean | null

```bash
curl --fail-with-body -X POST \
  "$EXULANICA_API_URL/world/versions/$VERSION_ID/objects?world_id=$WORLD_ID" \
  -H "Authorization: Bearer $EXULANICA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "base_state_sha256": "<current state digest>",
    "object_id": "tool:marker",
    "asset_sha256": "<catalog asset digest>",
    "region_id": "<region ID>",
    "transform": {
      "x_mm": 0, "y_mm": 0, "z_mm": 0,
      "yaw_microradians": 0, "scale_milli": 1000
    },
    "origin_role": "fictional"
  }'
```

```python
import json
import os
import urllib.request

url = os.environ["EXULANICA_API_URL"] + f'/world/versions/{os.environ["VERSION_ID"]}/objects?world_id={os.environ["WORLD_ID"]}'
headers = {
    "Authorization": "Bearer " + os.environ["EXULANICA_TOKEN"]
}
headers["Content-Type"] = "application/json"
body = {
    "base_state_sha256": "<current state digest>",
    "object_id": "tool:marker",
    "asset_sha256": "<catalog asset digest>",
    "region_id": "<region ID>",
    "transform": {
      "x_mm": 0, "y_mm": 0, "z_mm": 0,
      "yaw_microradians": 0, "scale_milli": 1000
    },
    "origin_role": "fictional"
  }
data = json.dumps(body).encode()
request = urllib.request.Request(
    url, data=data, headers=headers, method="POST"
)
with urllib.request.urlopen(request) as response:
    print(json.load(response))
```

**201 Response structure**

```json
{
  "schema_version": "integer",
  "version_id": "uuid",
  "world_id": "string",
  "source_snapshot_id": "uuid",
  "parent_version_id": "uuid | null",
  "title": "string",
  "origin": "string",
  "style_version_id": "uuid | null",
  "state_sha256": "string",
  "edit_seq": "integer",
  "source_invalidated": "boolean",
  "created_by": "uuid",
  "created_at": "string",
  "objects": [
    {
      "object_id": "string",
      "asset": "object | null",
      "workspace_asset": "object | null",
      "region_id": "string",
      "transform": "object",
      "origin": "object",
      "behaviour": "object | null",
      "removed": "boolean"
    }
  ],
  "element_overrides": [
    {
      "element_id": "string",
      "suppressed": "boolean",
      "transform": "object | null",
      "storeys": "integer | null"
    }
  ],
  "environment_instances": [
    "object"
  ],
  "point_map_instances": [
    "object"
  ],
  "things": [
    "object"
  ],
  "edits": [
    {
      "edit_id": "uuid",
      "edit_seq": "integer",
      "kind": "string",
      "object_id": "string | null",
      "element_id": "string | null",
      "environment_instance_id": "string | null",
      "point_map_instance_id": "string | null",
      "thing_id": "string | null",
      "undone_edit_id": "uuid | null",
      "base_state_sha256": "string",
      "result_state_sha256": "string",
      "actor": "uuid",
      "recorded_at": "string",
      "storeys": "object | null",
      "turned_in_place": "boolean | null"
    }
  ]
}
```

Types and structure, not a live response. Expand properties for the complete field definitions.

## Authentication

Send `Authorization: Bearer <token>` with a token for your workspace. Read operations require `world.read`; writes require `world.write`.

[Authentication and access](/docs/authentication)