Skip to main content
GET
https://app.commodityai.com
/
api
/
v1
/
objects
/
definitions
curl -X GET "https://app.commodityai.com/api/v1/objects/definitions?limit=50" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

{
  "data": [
    {
      "id": "456e7890-e89b-12d3-a456-426614174000",
      "name": "trades",
      "plural_name": "Trades",
      "description": "Commodity trade records",
      "key_prefix": "TRD",
      "icon": "trending-up",
      "version": "1.0",
      "primary_key_fields": ["trade_reference"],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    },
    {
      "id": "567e8901-e89b-12d3-a456-426614174001",
      "name": "shipments",
      "plural_name": "Shipments",
      "description": "Shipment tracking records",
      "key_prefix": "SHP",
      "icon": "ship",
      "version": "1.0",
      "primary_key_fields": ["bill_of_lading"],
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-18T11:45:00Z"
    }
  ],
  "meta": {
    "has_more": false,
    "next_cursor": null,
    "limit": 50
  }
}
Returns a paginated list of custom object definitions configured for your company. Object definitions describe the structure of business entities like trades, shipments, and contracts that are built from extracted source records.

​
Query Parameters

​
limit
number
default:"100"
Number of definitions to return (max: 1000)
​
cursor
string
Pagination cursor for fetching the next page of results

​
Request Examples

curl -X GET "https://app.commodityai.com/api/v1/objects/definitions?limit=50" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

​
Response

{
  "data": [
    {
      "id": "456e7890-e89b-12d3-a456-426614174000",
      "name": "trades",
      "plural_name": "Trades",
      "description": "Commodity trade records",
      "key_prefix": "TRD",
      "icon": "trending-up",
      "version": "1.0",
      "primary_key_fields": ["trade_reference"],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    },
    {
      "id": "567e8901-e89b-12d3-a456-426614174001",
      "name": "shipments",
      "plural_name": "Shipments",
      "description": "Shipment tracking records",
      "key_prefix": "SHP",
      "icon": "ship",
      "version": "1.0",
      "primary_key_fields": ["bill_of_lading"],
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-18T11:45:00Z"
    }
  ],
  "meta": {
    "has_more": false,
    "next_cursor": null,
    "limit": 50
  }
}

​
Response Fields

​
data
array
Array of object definition objects
​
meta
object
Pagination metadata

​
Common Use Cases

​
Get Definition ID for Record Queries

Use this endpoint to discover available object definitions and their IDs, which are required for the List Custom Object Records endpoint: 
// 1. List all object definitions
const defsResponse = await fetch(
  'https://app.commodityai.com/api/v1/objects/definitions',
  { headers: { 'Authorization': 'Bearer cai_live_your_api_key_here' } }
);
const definitions = await defsResponse.json();

// 2. Find the trades definition
const tradeDef = definitions.data.find(d => d.name === 'trades');

// 3. Fetch records for that definition
const recordsResponse = await fetch(
  `https://app.commodityai.com/api/v1/objects/${tradeDef.id}/records`,
  { headers: { 'Authorization': 'Bearer cai_live_your_api_key_here' } }
);
const records = await recordsResponse.json();

​
Understand Object Structure

The primary_key_fields array tells you which fields uniquely identify each object instance. This is useful for understanding how records are deduplicated and matched: 
const definitions = await fetchDefinitions();

definitions.data.forEach(def => {
  console.log(`${def.name}: unique by ${def.primary_key_fields.join(' + ')}`);
});

// Output:
// trades: unique by trade_reference
// shipments: unique by bill_of_lading
// contracts: unique by contract_id + counterparty

​
Error Codes

StatusCodeDescription
401unauthorizedInvalid or missing API key
429rate_limit_exceededToo many requests (see Rate Limits)
500internal_errorInternal server error