# LedgerHQ Agent Quickstart

LedgerHQ gives accounting agents scoped access to a firm's connected client files. Agents do not receive QBO credentials. They call LedgerHQ, and LedgerHQ brokers access, enforces client boundaries, and records audit events.

## 1. Create an API Key

In LedgerHQ:

1. Open **API Keys**.
2. Enter a name for the agent or workflow.
3. Choose **All current and future clients** or **Selected clients only**.
4. Choose a permission preset:
   - **Read-only client data** for agents that only inspect data.
   - **Full read/write QBO API access** for agents that query, create, edit, or delete QBO data through LedgerHQ.
5. Click **Create key**.
6. Copy the secret immediately. LedgerHQ will not show it again.

Store the secret in the agent host as an environment variable:

```text
LEDGERHQ_API_KEY=lhq_live_...
LEDGERHQ_API_BASE=https://ledgerhq.app/api/agent/v1
```

Do not paste the key into prompts, commit it to GitHub, store it in browser localStorage, or place it in shared notes.

## 2. Authenticate

Every request uses a bearer token:

```http
Authorization: Bearer lhq_live_...
```

Optional but recommended:

```http
X-LedgerHQ-Agent-Name: Monthly Close Agent
```

## 3. Smoke Test

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/status"
```

Expected:

```json
{
  "ok": true,
  "service": "ledgerhq-agent-api"
}
```

## 4. List Available Clients

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/clients"
```

The response only includes clients the key is allowed to access.

## 4a. Inspect QBO Coverage

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/coverage"
```

Use coverage before calling the generic entity gateway. It lists supported QBO entity names, operations, risk levels, and accepted scopes.

## 4b. Use The Broad QBO Integration API

Run a QBO query:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"select * from Customer maxresults 25"}' \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/query"
```

Call a relative QBO API path:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"GET","path":"reports/ProfitAndLoss","query":{"start_date":"2026-01-01","end_date":"2026-05-31"}}' \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/request"
```

## 4c. Learn QBO Workflows

Agents should use the playbook and recipes before attempting complex writes.

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/skills"
```

Public references:

- `https://ledgerhq.app/docs/agent-qbo-playbook.md`
- `https://ledgerhq.app/docs/agent-recipes.json`

## 5. Fetch One Client

```bash
CLIENT_ID="qbo-411909201"

curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID"
```

## 6. Fetch Reports and Lists

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/reports/profit-loss"
```

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/chart-accounts"
```

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/vendors"
```

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/customers"
```

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/transactions?entityType=purchase&maxResults=25"
```

Generic entity gateway:

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/entities/invoice?maxResults=25"
```

## 7. Write QBO Transactions

Only use a full read/write key for agents that are allowed to change live QBO data. LedgerHQ checks the key scope and client access before it posts anything to QBO.

Create:

```bash
curl -sS -X POST \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"purchase","payload":{"PaymentType":"Cash","AccountRef":{"value":"35"},"Line":[]}}' \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/transactions"
```

Update:

```bash
curl -sS -X PATCH \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"purchase","payload":{"SyncToken":"0","PrivateNote":"Updated by LedgerHQ agent"}}' \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/transactions/123"
```

Delete:

```bash
curl -sS -X DELETE \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityType":"purchase","syncToken":"0"}' \
  "$LEDGERHQ_API_BASE/qbo/clients/$CLIENT_ID/transactions/123"
```

Supported transaction types: `bill`, `bill-payment`, `credit-memo`, `deposit`, `estimate`, `invoice`, `journal-entry`, `payment`, `purchase`, `refund-receipt`, `sales-receipt`, `transfer`, and `vendor-credit`.

## 8. Run a Read-Only Scan

```bash
curl -sS \
  -H "Authorization: Bearer $LEDGERHQ_API_KEY" \
  "$LEDGERHQ_API_BASE/skills/client-health-scan"
```

## 9. Error Meanings

- `401 unauthorized`: missing, revoked, rotated, or incorrect API key.
- `403 scope_denied`: the key does not have the required permission.
- `403 client_access_denied`: the key is not allowed to access that client.
- `404 not_found`: the client or endpoint does not exist.
- `503 agent_auth_not_configured`: agent auth is not ready on the server.

## 10. Rotation and Revocation

Rotate a key when it might have been exposed. Revoke a key when an agent, vendor, workflow, or employee should lose access. After rotation, update the agent host with the new secret.

You can also change an existing key between **Read-only** and **Full read/write** from the API Keys page without rotating the secret. This is useful when an agent graduates from analysis-only work to QBO posting, or when a write-enabled agent needs to be restricted temporarily.

## 11. Permission Presets

### Read-only

- `clients:read`
- `qbo:query`
- `qbo:request`
- `qbo:entities:read`
- `qbo:reports:read`
- `qbo:chart_accounts:read`
- `qbo:vendors:read`
- `qbo:customers:read`
- `qbo:transactions:read`
- `audit:read`

### Full read/write

Full read/write keys include every read-only scope plus:

- `qbo:entities:create`
- `qbo:entities:update`
- `qbo:entities:delete`
- `qbo:entities:write`
- `qbo:transactions:create`
- `qbo:transactions:update`
- `qbo:transactions:delete`
- `qbo:attachments:write`
- `qbo:rules:write`
- `qbo:browser:write`
- `approvals:create`
- `jobs:create`

Use full read/write keys only for agents that are expected to change QBO data.