API Overview

REST API Overview

CargoLint provides a comprehensive REST API for document processing, data extraction, and customs compliance checking. This guide covers authentication, rate limiting, pagination, and error handling.

API access is available on Business and Enterprise plans.

Base URL

All API requests should be made to:

https://api.cargolint.com/api/v1

Content Types

The CargoLint API supports the following content types:

• JSON (application/json) - For all JSON request and response bodies
• Multipart Form Data (multipart/form-data) - For file uploads

Ensure your Content-Type header matches your request format.

Authentication

CargoLint supports two authentication methods:

Bearer Token Authentication

Include a JWT Bearer token in the Authorization header:

curl -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  https://api.cargolint.com/api/v1/documents

API Key Authentication

Include your API key in the X-API-Key header:

curl -H "X-API-Key: YOUR_API_KEY" \
  https://api.cargolint.com/api/v1/documents

Both methods provide equivalent access and can be used interchangeably.

Rate Limiting

API requests are rate limited to prevent abuse. The following limits apply based on your plan:

• Business Plan: 60 requests per minute
• Enterprise Plan: 300 requests per minute

Rate limit information is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
X-RateLimit-Reset: 1646256000

When you exceed the rate limit, the API returns a 429 Too Many Requests response.

Pagination

List endpoints support pagination using offset and limit query parameters:

curl "https://api.cargolint.com/api/v1/documents?offset=0&limit=20" \
  -H "X-API-Key: YOUR_API_KEY"

• offset - Number of items to skip (default: 0)
• limit - Maximum items to return (default: 20, max: 100)

Paginated responses include metadata:

{
  "data": [...],
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 150,
    "hasMore": true
  }
}

Error Handling

All errors follow a standard format:

{
  "error": "Descriptive error message",
  "code": "ERROR_CODE",
  "details": {}
}

Common HTTP Status Codes

Status	Meaning	Example
400	Bad Request	Missing required field
401	Unauthorized	Invalid or missing API key
403	Forbidden	Insufficient permissions
404	Not Found	Document does not exist
429	Rate Limited	Too many requests
500	Server Error	Internal service error

API Versioning

The current API version is v1. Future versions will be available at /api/v2, etc. The v1 version will remain stable for at least 12 months after a new version is released.

Example Request/Response

Request

curl -X GET "https://api.cargolint.com/api/v1/documents" \
  -H "X-API-Key: sk_test_YOUR_SECRET_KEY_HERE" \
  -H "Accept: application/json"

Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1646256000

Response Body

{
  "data": [
    {
      "id": "doc_abc123",
      "fileName": "invoice.pdf",
      "status": "processed",
      "documentType": "invoice",
      "createdAt": "2026-03-02T10:30:00Z"
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 20,
    "total": 1,
    "hasMore": false
  }
}

Getting Help

For API support, documentation, or integration assistance, contact our support team at support@cargolint.com.