API Reference Overview

Crane Ledger provides a comprehensive REST API for headless accounting operations. The API is built on a worker-based architecture that ensures reliable, scalable processing of complex financial operations while maintaining real-time performance for simple queries.

🏗️ Architecture Overview

Worker-Based Processing

Crane Ledger uses a sophisticated worker system to handle different types of operations:

Real-Time Operations (Direct Response)

Simple read operations (GET requests)
Account balance queries
List operations with filtering
System health checks

Background Operations (Worker-Queued)

Complex write operations (POST/PUT/DELETE)
Invoice/bill creation with PDF generation
Multi-step business processes
Heavy computational tasks

// Real-time: Immediate response
GET /organizations/{org_id}/accounts
// Returns: Account list instantly

// Worker-queued: Async processing
POST /organizations/{org_id}/invoices
// Returns: Job ID, processes in background

Request Flow

Client Request → Authentication → Route Matching → Processing Type
                                      │
                   ┌──────────────────┼──────────────────┐
                   │                  │                  │
            Real-time Response   Worker Queue      Error Response
                   │                  │                  │
            JSON Response      Job Status        Error Details

🔐 Authentication

All API requests require authentication using API keys:

# Include in all requests
Authorization: Bearer cl_live_your_api_key_here
# or
Authorization: Bearer cl_test_your_api_key_here

API Key Types

Live Keys (cl_live_): Production operations with real credit consumption
Test Keys (cl_test_): Development and testing with mock credit consumption

Organization Scoping

API keys are scoped to specific organizations:

// Key for Organization A
const apiKey_A = "cl_live_org_a_key_here"

// Key for Organization B
const apiKey_B = "cl_live_org_b_key_here"

📊 Credit System

Cost Structure

Every API operation consumes credits from your organization's pool:

Operation Type	Credits	Cost	Notes
Read Operations	0	Free	GET requests, listings
Simple Writes	1-2	$0.01-$0.02	Account updates, basic operations
Complex Operations	5-10	$0.05-$0.10	Invoice creation, reports

Credit Balance Monitoring

# Check credit balance
GET /organizations/{org_id}/billing

# Response
{
  "credits_remaining": 1500,
  "credits_total": 2000,
  "auto_recharge_enabled": true,
  "billing_email": "billing@company.com"
}

🗂️ API Organization

Resource Hierarchy

Organizations (Root)
├── Accounts (Chart of Accounts)
├── Transactions (Journal Entries)
├── Contacts (Customers/Vendors)
├── Invoices (Sales Documents)
├── Bills (Purchase Documents)
├── Reports (Financial Statements)
├── Transfers (Account Movements)
├── Reconciliations (Bank Matching)
├── Recurring (Scheduled Transactions)
├── API Keys (Access Management)
└── Settings (Configuration)

URL Structure

/organizations/{organization_id}/[resource]/[resource_id]/[action]

Examples:

# List accounts
GET /organizations/org_123/accounts

# Get specific account
GET /organizations/org_123/accounts/act_456

# Create transaction
POST /organizations/org_123/transactions

# Generate report
GET /organizations/org_123/reports/trial-balance

📋 Core Resources

Organization Management

Master accounts and sub-organizations for multi-tenant setups:

// Create master account
POST /accounts/master
{
  "organization_name": "My Business",
  "user_github_id": "12345678",
  "user_email": "user@business.com"
}

// Create sub-organization
POST /accounts/sub
{
  "parent_organization_id": "org_123",
  "organization_name": "European Division",
  "relationship_type": "owned"  // or "linked"
}

Chart of Accounts

Hierarchical account structure for double-entry bookkeeping:

// Create account
POST /organizations/{org_id}/accounts
{
  "code": "1001",
  "name": "Operating Cash",
  "type": "asset",
  "currency_id": "CUR_USD"
}

// Query account hierarchy
GET /organizations/{org_id}/accounts?include_hierarchy=true

Transaction Processing

Double-entry journal entries with validation:

// Create transaction
POST /organizations/{org_id}/transactions
{
  "description": "Cash sale",
  "entries": [
    {"account_id": "ACT_1001", "entry_type": "debit", "amount": 100.00},
    {"account_id": "ACT_4001", "entry_type": "credit", "amount": 100.00}
  ]
}

// Post transaction (make it final)
POST /organizations/{org_id}/transactions/{txn_id}/post

Financial Documents

Complete invoice and bill lifecycle management:

// Create invoice (worker-queued)
POST /organizations/{org_id}/invoices
{
  "contact_id": "CON_123",
  "items": [
    {"name": "Service", "quantity": 10, "price": 50.00}
  ]
}

// Record payment
POST /organizations/{org_id}/invoices/{inv_id}/payments
{
  "amount": 500.00,
  "payment_date": "2024-01-15"
}

📈 Reporting & Analytics

Financial Statements

Comprehensive reporting with real-time data:

// Trial balance
GET /organizations/{org_id}/reports/trial-balance

// Balance sheet
GET /organizations/{org_id}/reports/balance-sheet

// Income statement
GET /organizations/{org_id}/reports/income-statement

Custom Queries

Flexible filtering and date ranges:

# Filter transactions by date
GET /organizations/{org_id}/transactions?start_date=2024-01-01&end_date=2024-01-31

# Search contacts
GET /organizations/{org_id}/contacts?search=acme&type=customer

# Account transactions
GET /organizations/{org_id}/accounts/{act_id}/transactions?limit=50

🔄 Advanced Features

Multi-Currency Support

Handle international operations with automatic conversion:

// Set exchange rate
POST /organizations/{org_id}/exchange-rates
{
  "from_currency_id": "CUR_USD",
  "to_currency_id": "CUR_EUR",
  "rate": 0.85,
  "effective_date": "2024-01-15"
}

// Currency conversion
POST /currencies/convert
{
  "from_currency": "USD",
  "to_currency": "EUR",
  "amount": 1000.00
}

Bank Reconciliation

Match transactions to bank statements:

// Start reconciliation
POST /organizations/{org_id}/reconciliations
{
  "account_id": "ACT_1001",
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "closing_balance": 15750.00
}

// Complete reconciliation
POST /organizations/{org_id}/reconciliations/{rec_id}/complete

Recurring Transactions

Automate regular financial operations:

// Create recurring invoice
POST /organizations/{org_id}/recurring
{
  "recurable_type": "invoice",
  "recurable_id": "INV_123",
  "frequency": "monthly",
  "interval": 1,
  "auto_send": true
}

🔧 API Management

API Key Administration

Manage access credentials programmatically:

// Create API key
POST /organizations/{org_id}/api-keys
{
  "name": "Production App",
  "permissions": ["read", "write"]
}

// Rotate key
POST /organizations/{org_id}/api-keys/{key_id}/rotate

Organization Settings

Configure system behavior:

// Update setting
PUT /organizations/{org_id}/settings/default_currency
{
  "value": "EUR"
}

// Get setting
GET /organizations/{org_id}/settings/default_currency

📊 Rate Limiting

Limits by Key Type

Live Keys: 1000 requests per minute
Test Keys: 100 requests per minute

Burst Handling

// Rate limit headers in response
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

🚨 Error Handling

Standard Error Responses

{
  "error": {
    "type": "validation_error",
    "message": "Transaction does not balance",
    "details": {
      "total_debits": 150.00,
      "total_credits": 100.00,
      "difference": 50.00
    }
  }
}

Common Error Types

authentication_error: Invalid API key
authorization_error: Insufficient permissions
validation_error: Invalid request data
business_rule_error: Business logic violation
rate_limit_error: Too many requests
credit_limit_error: Insufficient credits

🔍 Event Tracking

Audit Trail

Complete history of all operations:

// Get entity events
GET /events/transactions/TXN_123

// Response
[
  {
    "event_type": "transaction.posted",
    "entity_type": "transaction",
    "entity_id": "TXN_123",
    "timestamp": "2024-01-15T10:30:00Z",
    "api_key_id": "KEY_456",
    "before_state": null,
    "after_state": { /* full transaction */ }
  }
]

🛠️ Development Tools

API Playground

Interactive testing environment:

# Access playground
GET /api/playground

# Or integrate with external tools
npm install @craneledger/api-client

SDKs & Libraries

Official client libraries:

// JavaScript/TypeScript
import { CraneLedger } from '@craneledger/js-sdk';

const client = new CraneLedger({
  apiKey: 'cl_live_your_key_here',
  organizationId: 'org_123'
});

// TypeScript support with full type safety
const accounts = await client.accounts.list();

📚 Quick Start Examples

1. Set Up Organization

# Create master account
curl -X POST https://api.craneledger.ai/accounts/master \
  -H "Content-Type: application/json" \
  -d '{
    "organization_name": "My Business",
    "user_github_id": "12345678",
    "user_email": "user@business.com"
  }'

2. Create Chart of Accounts

# Create cash account
curl -X POST https://api.craneledger.ai/organizations/{org_id}/accounts \
  -H "Authorization: Bearer cl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "1001",
    "name": "Operating Cash",
    "type": "asset",
    "currency_id": "CUR_USD"
  }'

3. Record First Transaction

# Record opening balance
curl -X POST https://api.craneledger.ai/organizations/{org_id}/transactions \
  -H "Authorization: Bearer cl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Opening cash balance",
    "entries": [
      {"account_id": "ACT_1001", "entry_type": "debit", "amount": 10000.00},
      {"account_id": "ACT_3001", "entry_type": "credit", "amount": 10000.00}
    ]
  }'

4. Generate Report

# Get trial balance
curl https://api.craneledger.ai/organizations/{org_id}/reports/trial-balance \
  -H "Authorization: Bearer cl_live_your_key"

🚀 Production Considerations

Error Handling

// Implement retry logic
async function apiCall(endpoint, options = {}) {
  const maxRetries = 3;
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const response = await fetch(endpoint, options);

      if (response.status === 429) {
        // Rate limited, wait and retry
        await new Promise(r => setTimeout(r, 1000 * (attempt + 1)));
        attempt++;
        continue;
      }

      if (!response.ok) {
        throw new Error(`API Error: ${response.status}`);
      }

      return await response.json();
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
      attempt++;
    }
  }
}

Credit Monitoring

// Monitor credit balance
async function checkCredits() {
  const billing = await apiCall('/organizations/{org_id}/billing');

  if (billing.credits_remaining < 100) {
    console.warn('Low credit balance:', billing.credits_remaining);
    // Trigger recharge or alert
  }
}

Batch Operations

// Process multiple operations efficiently
async function batchCreateContacts(contacts) {
  const results = [];

  for (const contact of contacts) {
    try {
      const result = await apiCall('/organizations/{org_id}/contacts', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(contact)
      });
      results.push(result);
    } catch (error) {
      console.error('Failed to create contact:', contact.name, error);
    }
  }

  return results;
}

The Crane Ledger API provides everything you need for comprehensive accounting operations. From simple balance checks to complex multi-entity consolidations, the worker-based architecture ensures reliable processing at any scale.

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.

✨ For LLMs/AI assistants: Read our structured API reference