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

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "invoices",
      "description": "Invoice extraction for accounts payable",
      "source_types": ["email", "document"],
      "email_address": "[email protected]",
      "version": "1.0",
      "record_identifier_prefix": "INV",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    },
    {
      "id": "223e4567-e89b-12d3-a456-426614174001",
      "name": "contracts",
      "description": "Trade contract extraction",
      "source_types": ["document"],
      "email_address": null,
      "version": "1.0",
      "record_identifier_prefix": "CON",
      "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 source record definitions configured for your company. Source definitions describe the structure of data extracted from documents like invoices, contracts, and bills of lading.

​
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/sources/definitions?limit=50" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

​
Response

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "invoices",
      "description": "Invoice extraction for accounts payable",
      "source_types": ["email", "document"],
      "email_address": "[email protected]",
      "version": "1.0",
      "record_identifier_prefix": "INV",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    },
    {
      "id": "223e4567-e89b-12d3-a456-426614174001",
      "name": "contracts",
      "description": "Trade contract extraction",
      "source_types": ["document"],
      "email_address": null,
      "version": "1.0",
      "record_identifier_prefix": "CON",
      "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 source definition objects
​
meta
object
Pagination metadata

​
Common Use Cases

​
Get Definition ID for Record Queries

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

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

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

​
Error Codes

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