API Overview

The lim REST API provides programmatic access to all accounting operations. It powers the CLI, the web dashboard, MCP server, and third-party integrations.

Base URL

https://api.uselim.com/v1

All API endpoints are versioned under /v1. The base URL may differ for self-hosted deployments.

Authentication

lim uses OAuth 2.0 via WorkOS for authentication. All API requests require a valid bearer token.

Obtaining a Token

lim auth login
# Opens browser for OAuth flow
# Token stored in ~/.config/lim/credentials.json

# Create an API key in the web dashboard or via API
# Then use it as a bearer token
curl -H "Authorization: Bearer lim_sk_..." https://api.uselim.com/v1/...

Using the Token

Include the token in the Authorization header:

curl -X GET https://api.uselim.com/v1/companies \
  -H "Authorization: Bearer <token>"

Never expose API keys in client-side code, public repositories, or logs. Use environment variables or secret management tools.

Request Format

Content-Type: application/json for all request bodies
Date format: YYYY-MM-DD for dates, ISO 8601 for timestamps
Amounts: Integers in the smallest currency unit (yen for JPY, cents for USD)
IDs: UUID v7 format

Example Request

curl -X POST https://api.uselim.com/v1/companies/comp_01.../journal-entries \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "effectiveDate": "2026-03-16",
    "sourceType": "manual",
    "memo": "AWS monthly bill",
    "lines": [
      { "side": "debit",  "accountId": "acct_01...", "amount": 10000 },
      { "side": "debit",  "accountId": "acct_02...", "amount": 1000 },
      { "side": "credit", "accountId": "acct_03...", "amount": 11000 }
    ]
  }'

Response Format

All responses are JSON. Successful responses return the resource directly:

{
  "id": "je_01926f3a...",
  "effectiveDate": "2026-03-16",
  "status": "posted",
  "memo": "AWS monthly bill",
  "lines": [
    { "side": "debit", "accountId": "acct_01...", "accountCode": "5101", "amount": 10000 },
    { "side": "debit", "accountId": "acct_02...", "accountCode": "1501", "amount": 1000 },
    { "side": "credit", "accountId": "acct_03...", "accountCode": "2101", "amount": 11000 }
  ],
  "createdAt": "2026-03-16T09:30:00.000Z"
}

List endpoints return arrays with pagination info:

{
  "data": [...],
  "total": 150,
  "limit": 50,
  "offset": 0
}

Error Format

Errors return a JSON object with an error field and an appropriate HTTP status code:

{
  "error": "from and to query parameters are required"
}

Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Bad request — missing or invalid parameters
`401`	Unauthorized — invalid or missing token
`403`	Forbidden — insufficient permissions
`404`	Not found
`409`	Conflict — resource already exists (unique constraint)
`429`	Rate limited
`500`	Internal server error

Error messages are safe to display to users. Internal details and stack traces are never leaked in error responses.

Rate Limiting

API requests are rate-limited per authentication token:

Plan	Rate Limit
Free	100 requests/minute
Pro	1,000 requests/minute
Enterprise	Custom

When rate-limited, the API returns 429 Too Many Requests with a Retry-After header:

HTTP/1.1 429 Too Many Requests
Retry-After: 30

Endpoint Overview

All endpoints are scoped to a company: /v1/companies/:companyId/...

Core Resources

Method	Endpoint	Description
`GET`	`/companies`	List companies
`POST`	`/companies`	Create company
`GET`	`/companies/:id`	Get company

Accounting

Method	Endpoint	Description
`GET`	`/companies/:id/journal-entries`	List journal entries
`POST`	`/companies/:id/journal-entries`	Create journal entry
`GET`	`/companies/:id/journal-entries/:jeId`	Get journal entry
`POST`	`/companies/:id/nl-journal`	Natural language journal entry
`GET`	`/companies/:id/accounts`	List accounts
`GET`	`/companies/:id/accounts/:acctId`	Get account
`GET`	`/companies/:id/tax-codes`	List tax codes
`GET`	`/companies/:id/labels`	List labels

Reports

Method	Endpoint	Description
`GET`	`/companies/:id/reports/trial-balance`	Trial balance
`GET`	`/companies/:id/reports/pl`	Profit & loss
`GET`	`/companies/:id/reports/bs`	Balance sheet
`GET`	`/companies/:id/reports/ss`	Shareholders’ equity
`GET`	`/companies/:id/reports/cs`	Cash flow statement
`GET`	`/companies/:id/reports/general-ledger`	General ledger
`GET`	`/companies/:id/reports/subsidiary-summary`	Subsidiary summary
`GET`	`/companies/:id/reports/ar-aging`	AR aging
`GET`	`/companies/:id/reports/consumption-tax`	Consumption tax
`GET`	`/companies/:id/reports/consumption-tax/xml`	e-Tax XML export
`GET`	`/companies/:id/reports/account-details`	Account details

Banking

Method	Endpoint	Description
`GET`	`/companies/:id/bank-accounts`	List bank accounts
`POST`	`/companies/:id/bank-accounts`	Create bank account
`GET`	`/companies/:id/bank-accounts/:baId/transactions`	List transactions

Operations

Method	Endpoint	Description
`GET`	`/companies/:id/scenarios`	List scenarios
`POST`	`/companies/:id/scenarios`	Create scenario
`GET`	`/companies/:id/alert-rules`	List alert rules
`POST`	`/companies/:id/alert-rules`	Create alert rule
`GET`	`/companies/:id/fiscal-periods`	List fiscal periods
`POST`	`/companies/:id/fiscal-periods/:fpId/close`	Close period
`GET`	`/companies/:id/contracts`	List contracts
`GET`	`/companies/:id/invoices`	List invoices
`GET`	`/companies/:id/expense-reports`	List expense reports
`GET`	`/companies/:id/employees`	List employees
`POST`	`/companies/:id/payroll/run`	Run payroll
`GET`	`/companies/:id/fixed-assets`	List fixed assets
`GET`	`/companies/:id/accrual-schedules`	List accrual schedules
`GET`	`/companies/:id/documents`	List documents

Dashboard & Events

Method	Endpoint	Description
`GET`	`/companies/:id/dashboard`	Dashboard summary
`GET`	`/companies/:id/events`	List events

MCP

Method	Endpoint	Description
`GET`	`/mcp/resources`	List MCP resources
`GET`	`/mcp/resources/:uri`	Read MCP resource
`GET`	`/mcp/tools`	List MCP tools
`POST`	`/mcp/tools/:name`	Call MCP tool

A full OpenAPI specification is available at https://api.uselim.com/openapi.json. You can import it into Postman, Insomnia, or any OpenAPI-compatible tool for interactive exploration.

​API Overview

​Base URL

​Authentication

​Obtaining a Token

​Using the Token

​Request Format

​Example Request

​Response Format

​Error Format

​Status Codes

​Rate Limiting

​Endpoint Overview

​Core Resources

​Accounting

​Reports

​Banking

​Operations

​Dashboard & Events

​MCP

API Overview

Base URL

Authentication

Obtaining a Token

Using the Token

Request Format

Example Request

Response Format

Error Format

Status Codes

Rate Limiting

Endpoint Overview

Core Resources

Accounting

Reports

Banking

Operations

Dashboard & Events

MCP