REST API 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.

Base URL

All REST API requests use the following base URL:

https://api.craneledger.ai

Base URL

https://api.craneledger.ai

All API requests must be made over HTTPS. Calls made over plain HTTP will fail.

Architecture

Worker-Based Processing

Crane Ledger uses a 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

URL Structure

All resources are scoped under an organization:

/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

Request Format

Headers

All requests must include:

Header	Required	Description
`Authorization`	Yes	`Bearer cl_live_xxx` or `Bearer cl_test_xxx`
`Content-Type`	Yes (for POST/PUT)	`application/json`

Request Body

For POST and PUT requests, send a JSON body:

{
  "name": "Operating Cash",
  "code": "1001",
  "type": "asset",
  "currency_id": "CUR_USD"
}

Response Format

Success Responses

Successful responses return JSON with the requested data. List endpoints return a consistent structure:

{
  "object": "list",
  "data": [ /* array of resources */ ],
  "has_more": false,
  "total_count": 42
}

Single-resource endpoints return the resource object directly:

{
  "id": "act_xxxxxxxxxxxxxxxx",
  "object": "account",
  "organization_id": "org_xxxxxxxxxxxxxxxx",
  "name": "Cash",
  "code": "1000",
  "type": "asset",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}

HTTP Status Codes

Code	Meaning
200	Success (GET, PUT, PATCH)
201	Created (POST)
204	No Content (DELETE)
400	Bad Request – validation or invalid data
401	Unauthorized – invalid or missing API key
403	Forbidden – insufficient permissions
404	Not Found – resource does not exist
429	Too Many Requests – rate limit exceeded
500	Server error – retry with backoff

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)

For detailed endpoint documentation, see the API Reference section.

Credit System

Every API operation consumes credits from your organization's pool. Read operations typically cost 0 credits; write and complex operations consume credits based on the operation type. Monitor your balance via the Dashboard or the billing endpoint.

Next Steps

Authentication – API keys and request signing
Errors – Error response format and handling
Pagination – Listing and paging through results
Rate Limits – Quotas and retry strategies

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