> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselim.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Overview

> REST API reference for lim: authentication, request format, error handling, and rate limits.

# 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](https://workos.com) for authentication. All API requests require a valid bearer token.

### Obtaining a Token

<CodeGroup>
  ```bash CLI (interactive) theme={null}
  lim auth login
  # Opens browser for OAuth flow
  # Token stored in ~/.config/lim/credentials.json
  ```

  ```bash API Key (programmatic) theme={null}
  # 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/...
  ```
</CodeGroup>

### Using the Token

Include the token in the `Authorization` header:

```bash theme={null}
curl -X GET https://api.uselim.com/v1/companies \
  -H "Authorization: Bearer <token>"
```

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

## 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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "data": [...],
  "total": 150,
  "limit": 50,
  "offset": 0
}
```

## Error Format

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

```json theme={null}
{
  "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                                   |

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

## 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      |

<Tip>
  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.
</Tip>