Skip to main content
Get up and running with the CommodityAI API in minutes. This guide walks you through creating an API key and making your first request.

​
Step 1: Create an API Key

In the CommodityAI dashboard, navigate to Settings → API Keys:
  1. Click “Create API Key”
  2. Enter a descriptive name (e.g., “Production Integration” or “Development Key”)
  3. Select the environment:
    • live - Production data
    • test - Development and testing
  4. Copy the key immediately - it won’t be shown again!
Your API key format will be: cai_live_a1b2c3d4... (live) or cai_test_a1b2c3d4... (test) followed by 64 hex characters.

​
Step 2: Get Your Definition ID

To query data, you’ll need a definition ID for the records you want to access:
  1. In the CommodityAI dashboard, go to Settings
  2. Navigate to Source Record Definitions or Custom Object Definitions
  3. Copy the UUID for the definition you want to query
The definition ID is a UUID like 660e8400-e29b-41d4-a716-446655440000

​
Step 3: Make Your First API Request

Replace {definition-id} with your actual definition ID and use your API key: 
curl -H "Authorization: Bearer cai_live_your_key_here" \
  "https://app.commodityai.com/api/v1/sources/{definition-id}/records?limit=10"

​
Available Endpoints

  • Source Records: GET /api/v1/sources/{definition-id}/records
  • Custom Objects: GET /api/v1/objects/{definition-id}/records

​
Understanding the Response

All responses follow this structure: 
{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "definition_id": "660e8400-e29b-41d4-a716-446655440000",
      "definition_name": "invoices",
      "record_data": {
        "invoice_number": "INV-001",
        "amount": 1250.50,
        "vendor": "ACME Corp"
      },
      "metadata": {
        "review_status": "approved",
        "confidence": "high"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:22:00Z"
    }
  ],
  "meta": {
    "has_more": true,
    "next_cursor": "eyJpZCI6IjEyMyJ9",
    "limit": 10
  }
}

​
Key Response Fields

  • data - Array of records matching your query
  • record_data - The extracted structured data
  • metadata - Record status, confidence, timestamps
  • meta.has_more - Whether more pages exist
  • meta.next_cursor - Token for fetching the next page

​
Common Query Parameters

Customize your requests with these parameters:
  • limit - Records per page (default: 100, max: 1000)
  • cursor - Pagination token from previous response
  • record_counter[gte] - Filter by counter (e.g., record_counter[gte]=5)
  • created_at[gte] - Filter by timestamp (e.g., created_at[gte]=2024-01-01T00:00:00Z)
# Get next page using cursor
curl -H "Authorization: Bearer cai_live_..." \
  "https://app.commodityai.com/api/v1/sources/{definition-id}/records?cursor=eyJpZCI6IjEyMyJ9"

​
Next Steps

Authentication

Learn about API key security and best practices

API Endpoints

Explore full API endpoint documentation

Rate Limits

Understand rate limiting and headers

Error Handling

Handle errors and edge cases

​
Need Help?

  • API Questions: Check the API Reference for detailed documentation
  • Technical Support: Contact [email protected]
  • Issues: Report bugs or request features through your account manager