Skip to main content
PUT
https://app.commodityai.com
/
api
/
v1
/
objects
/
{definition_id}
/
records
/
{record_id}
curl -X PUT "https://app.commodityai.com/api/v1/objects/234e4567-e89b-12d3-a456-426614174111/records/990e8400-e29b-41d4-a716-446655440004" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "record_data": {
      "quantity": 125000,
      "price_per_unit": 6.50
    },
    "metadata": {
      "status": "active"
    },
    "partial": true
  }'

{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "definition_id": "234e4567-e89b-12d3-a456-426614174111",
    "definition_name": "contracts",
    "primary_key_hash": "def456ghi789",
    "record_counter": 44,
    "record_data": {
      "contract_number": "CON-2024-044",
      "counterparty": "Pacific Trading Corp",
      "commodity": "Wheat",
      "quantity": 125000,
      "price_per_unit": 6.50,
      "delivery_date": "2024-05-01"
    },
    "metadata": {
      "record_identifier": "CON-2024-044",
      "status": "active"
    },
    "created_at": "2024-01-22T14:30:00Z",
    "updated_at": "2024-01-22T16:45:00Z"
  }
}
Updates an existing record within the specified object definition. Supports both full replacement and partial updates.

​
Path Parameters

​
definition_id
string
required
The unique identifier (UUID) of the object definition
​
record_id
string
required
The unique identifier (UUID) of the record to update

​
Request Body

​
record_data
object
required
The updated field values for the record. For partial updates, include only the fields to modify.
​
metadata
object
Updated metadata to associate with the record
​
partial
boolean
default:"false"
When true, performs a partial update (merge). When false, replaces all record_data fields.

​
Request Examples

curl -X PUT "https://app.commodityai.com/api/v1/objects/234e4567-e89b-12d3-a456-426614174111/records/990e8400-e29b-41d4-a716-446655440004" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "record_data": {
      "quantity": 125000,
      "price_per_unit": 6.50
    },
    "metadata": {
      "status": "active"
    },
    "partial": true
  }'

​
Response

{
  "data": {
    "id": "990e8400-e29b-41d4-a716-446655440004",
    "definition_id": "234e4567-e89b-12d3-a456-426614174111",
    "definition_name": "contracts",
    "primary_key_hash": "def456ghi789",
    "record_counter": 44,
    "record_data": {
      "contract_number": "CON-2024-044",
      "counterparty": "Pacific Trading Corp",
      "commodity": "Wheat",
      "quantity": 125000,
      "price_per_unit": 6.50,
      "delivery_date": "2024-05-01"
    },
    "metadata": {
      "record_identifier": "CON-2024-044",
      "status": "active"
    },
    "created_at": "2024-01-22T14:30:00Z",
    "updated_at": "2024-01-22T16:45:00Z"
  }
}

​
Response Fields

​
data
object
The updated object record

​
Update Modes

​
Full Replacement (default)

When partial is false or omitted, the entire record_data object is replaced. Any fields not included in the request will be removed. 
{
  "record_data": {
    "contract_number": "CON-2024-044",
    "counterparty": "Pacific Trading Corp",
    "commodity": "Wheat",
    "quantity": 125000,
    "price_per_unit": 6.50,
    "delivery_date": "2024-05-01"
  },
  "partial": false
}

​
Partial Update (merge)

When partial is true, only the specified fields are updated. Existing fields not included in the request are preserved. 
{
  "record_data": {
    "quantity": 125000,
    "price_per_unit": 6.50
  },
  "partial": true
}

​
Error Codes

StatusCodeDescription
400validation_errorInvalid or malformed request body
401unauthorizedInvalid or missing API key
404not_foundObject definition or record not found
409duplicate_recordUpdate would create a duplicate primary key
422schema_mismatchRecord data does not match the definition schema
429rate_limit_exceededToo many requests (see Rate Limits)
500internal_errorInternal server error