Skip to main content
POST
https://app.commodityai.com
/
api
/
v1
/
objects
/
{id}
/
records
curl -X POST "https://app.commodityai.com/api/v1/objects/234e4567-e89b-12d3-a456-426614174111/records" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "record_data": {
      "contract_number": "CON-2024-044",
      "counterparty": "Pacific Trading Corp",
      "commodity": "Wheat",
      "quantity": 100000,
      "price_per_unit": 6.75,
      "delivery_date": "2024-05-01"
    },
    "metadata": {
      "record_identifier": "CON-2024-044",
      "status": "draft"
    }
  }'

{
  "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": 100000,
      "price_per_unit": 6.75,
      "delivery_date": "2024-05-01"
    },
    "metadata": {
      "record_identifier": "CON-2024-044",
      "status": "draft"
    },
    "created_at": "2024-01-22T14:30:00Z",
    "updated_at": "2024-01-22T14:30:00Z"
  }
}
Creates a new record within the specified object definition. The record data must conform to the definition’s schema.

​
Path Parameters

​
id
string
required
The unique identifier (UUID) of the object definition

​
Request Body

​
record_data
object
required
The field values for the record. Structure must match the object definition’s schema.
​
metadata
object
Optional metadata to associate with the record (e.g., identifiers, status flags)

​
Request Examples

curl -X POST "https://app.commodityai.com/api/v1/objects/234e4567-e89b-12d3-a456-426614174111/records" \
  -H "Authorization: Bearer cai_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "record_data": {
      "contract_number": "CON-2024-044",
      "counterparty": "Pacific Trading Corp",
      "commodity": "Wheat",
      "quantity": 100000,
      "price_per_unit": 6.75,
      "delivery_date": "2024-05-01"
    },
    "metadata": {
      "record_identifier": "CON-2024-044",
      "status": "draft"
    }
  }'

​
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": 100000,
      "price_per_unit": 6.75,
      "delivery_date": "2024-05-01"
    },
    "metadata": {
      "record_identifier": "CON-2024-044",
      "status": "draft"
    },
    "created_at": "2024-01-22T14:30:00Z",
    "updated_at": "2024-01-22T14:30:00Z"
  }
}

​
Response Fields

​
data
object
The created object record

​
Error Codes

StatusCodeDescription
400validation_errorInvalid or malformed request body
401unauthorizedInvalid or missing API key
404not_foundObject definition not found with the provided ID
409duplicate_recordA record with the same primary key already exists
422schema_mismatchRecord data does not match the definition schema
429rate_limit_exceededToo many requests (see Rate Limits)
500internal_errorInternal server error