Skip to main content
GET
https://commodityai.app
/
api
/
v1
/
objects
/
{id}
/
records
/
{recordId}
/
sources
curl -X GET "https://commodityai.app/api/v1/objects/234e4567-e89b-12d3-a456-426614174111/records/770e8400-e29b-41d4-a716-446655440002/sources" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

{
  "data": {
    "documents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "filename": "contract_pages_1-5.pdf",
        "mime_type": "application/pdf",
        "size": 380000,
        "page_start": 1,
        "page_end": 5,
        "classification": "contracts",
        "uploaded_at": "2024-01-15T10:30:00Z",
        "download_url": "https://storage.example.com/signed/...",
        "download_url_expires_at": "2024-01-15T11:30:00Z"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "filename": "addendum_pages_1-2.pdf",
        "mime_type": "application/pdf",
        "size": 125000,
        "page_start": 1,
        "page_end": 2,
        "classification": "addendums",
        "uploaded_at": "2024-01-16T14:00:00Z",
        "download_url": "https://storage.example.com/signed/...",
        "download_url_expires_at": "2024-01-15T11:30:00Z"
      }
    ],
    "files": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "filename": "contract_bundle.pdf",
        "mime_type": "application/pdf",
        "size": 2500000,
        "page_count": 25,
        "download_url": "https://storage.example.com/signed/...",
        "download_url_expires_at": "2024-01-15T11:30:00Z"
      }
    ]
  }
}
Returns the source documents and files linked to a custom object record, including signed download URLs with a 1-hour expiry. Documents and files are discovered via bidirectional links to the record.

​
Path Parameters

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

​
Request Examples

curl -X GET "https://commodityai.app/api/v1/objects/234e4567-e89b-12d3-a456-426614174111/records/770e8400-e29b-41d4-a716-446655440002/sources" \
  -H "Authorization: Bearer cai_live_your_api_key_here"

​
Response

{
  "data": {
    "documents": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "filename": "contract_pages_1-5.pdf",
        "mime_type": "application/pdf",
        "size": 380000,
        "page_start": 1,
        "page_end": 5,
        "classification": "contracts",
        "uploaded_at": "2024-01-15T10:30:00Z",
        "download_url": "https://storage.example.com/signed/...",
        "download_url_expires_at": "2024-01-15T11:30:00Z"
      },
      {
        "id": "660e8400-e29b-41d4-a716-446655440001",
        "filename": "addendum_pages_1-2.pdf",
        "mime_type": "application/pdf",
        "size": 125000,
        "page_start": 1,
        "page_end": 2,
        "classification": "addendums",
        "uploaded_at": "2024-01-16T14:00:00Z",
        "download_url": "https://storage.example.com/signed/...",
        "download_url_expires_at": "2024-01-15T11:30:00Z"
      }
    ],
    "files": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440002",
        "filename": "contract_bundle.pdf",
        "mime_type": "application/pdf",
        "size": 2500000,
        "page_count": 25,
        "download_url": "https://storage.example.com/signed/...",
        "download_url_expires_at": "2024-01-15T11:30:00Z"
      }
    ]
  }
}

​
Response Fields

​
data
object
Container for documents and files
Documents vs Files: A file is the original uploaded document (e.g., a 25-page PDF). A document is a page range extracted from a file during processing (e.g., pages 1-5 classified as a contract). A single file may produce multiple documents.
Unlike source records, custom object record documents do not include an is_primary field, since custom object records can be linked to documents from multiple different ingestions.

​
Response Headers

All successful responses include rate limit headers to help you monitor your API usage:
​
X-RateLimit-Limit-Minute
number
Maximum number of requests allowed per minute (100)
​
X-RateLimit-Remaining-Minute
number
Number of requests remaining in the current minute
​
X-RateLimit-Reset-Minute
number
Unix timestamp (in seconds) when the per-minute limit resets
​
X-RateLimit-Limit-Day
number
Maximum number of requests allowed per day (10,000)
​
X-RateLimit-Remaining-Day
number
Number of requests remaining in the current day
​
X-RateLimit-Reset-Day
number
Unix timestamp (in seconds) when the daily limit resets
For more information on rate limits and how to handle them, see Rate Limits.

​
Error Codes

StatusCodeDescription
401unauthorizedInvalid or missing API key
404not_foundCustom object definition or record not found
429rate_limit_exceededToo many requests (see Rate Limits)
500internal_errorInternal server error