Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.commodityai.io/llms.txt

Use this file to discover all available pages before exploring further.

Get up and running with the CommodityAI API in minutes. This guide walks through API access for records and definitions. In the dashboard, those records may represent extracted source data, configurable custom objects, or source material linked to standard commodity objects such as contracts, shipments, and counterparties.
CommodityAI’s operating model is centered on standard commodity objects. The API endpoints in this guide are the general record and definition endpoints used for integration and source-data access.

​
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 extracted or configurable records, you’ll need a definition ID:
  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
Source definitions usually describe document-derived records. Object definitions describe configurable business records. Standard commodity objects are managed in their own workspace surfaces and can retain links back to source records and documents.

​
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://commodityai.app/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://commodityai.app/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 support@commodityai.io
  • Issues: Report bugs or request features through your account manager