---
name: hrc-ledger
description: Use the HRC Ledger API to read US healthcare contracts and organizations, work with the customer's saved Lists, action plans, drafts and conversations, and ask the HRC Ledger assistant. Use when the person wants their app or agent to call HRC Ledger.
license: Proprietary. Use of the API is under the HRC Ledger terms at https://hrcledger.com/terms.
compatibility: Any agent or language that can send HTTPS requests with a header. The key is made by a person in the HRC Ledger app.
---

# HRC Ledger API

HRC Ledger's API lives at `https://hrcledger.com/api/v1`. Every call needs an API
key in one header: `Authorization: Bearer <key>`. Every answer is
`{ "ok": true, "data": ... }` or `{ "ok": false, "error": { "code", "message" } }`.

## Ask the person before you

- [ ] make or change anything in their HRC Ledger account (a List, a plan, a draft);
- [ ] approve a draft or a plan;
- [ ] delete or archive anything;
- [ ] use `ask`, which spends your plan's weekly usage;
- [ ] write the key into any file. Keep it in an environment variable or a secret store.

Never print the key in a log, a commit or a chat.

## Get a key

A person makes the key. You cannot make one for them.

1. Ask them to sign in at https://hrcledger.com and open
   https://hrcledger.com/settings/api-keys.
2. Ask them to tick only the scopes the app needs. `contracts:read` and
   `market:read` are ticked for them. The scopes are listed at
   https://docs.hrcledger.com/developer/keys-and-scopes.
3. Ask them to press **Create key** and copy the key. It starts with `hck_live_`
   and is shown one time only.
4. Ask them to put it in an environment variable, such as `HRC_LEDGER_KEY`.

## Make a first call

```sh
curl -s -H "Authorization: Bearer $HRC_LEDGER_KEY" \
  "https://hrcledger.com/api/v1/contracts?q=ehr&limit=1"
```

## Verify

The call worked when the answer has `"ok": true`. If it has `"ok": false`, read
`error.code`:

- `missing_or_malformed_key` or `invalid_key`: the header or the key is wrong.
- `insufficient_scope`: the key needs the scope named in `error.scope`. The person
  makes a new key with it.
- `rate_limited`: wait for the seconds in the `Retry-After` header.

Every code is at https://docs.hrcledger.com/developer/errors.

## Operations

Each route below is on `https://hrcledger.com`. The contract
(https://hrcledger.com/docs/api/openapi.json) has every field and example.
Send an `Idempotency-Key` header on a call that makes something, so a retry makes it
once.

<!-- BEGIN GENERATED: skill-operations (scripts/render-registry-tables.ts; edit the registry, not this block) -->

| Operation | Route | Scope | What it does |
|---|---|---|---|
| `search_contracts` | `GET /api/v1/contracts` | `contracts:read` | Search contracts and bids by words, buyer, place, code, value and dates, with each contract's points of contact; a person shown counts against the week's contacts. Use this when someone asks what a buyer has bought or is buying. |
| `search_organizations` | `GET /api/v1/market/orgs` | `market:read` | Search provider organizations by segment, state, metro, beds and name, largest first. Use this when someone asks which hospitals, systems or clinics exist in a market. |
| `query` | MCP only | `data:query` | Run one read-only SELECT over the agent.* views, each relation schema-qualified, with a 5-second timeout; you get the rows, the total and what was cut. Read vocabulary first for the views and their values. Use this when the searches cannot filter or join what you need. |
| `vocabulary` | MCP only | `data:query` | The views query may read, with their columns and coverage (part views), or the closed sets their columns hold (part values). Use this when you write a query statement and need the exact spelling of a view, a column or a value. |
| `list_lists` | `GET /api/v1/lists` | `lists:read` | Your saved Lists of organizations, newest change first, without their rows. Use this when you need a List's id, or want to see which Lists exist before reading one. |
| `read_list` | `GET /api/v1/lists/{id}` | `lists:read` | One List and a page of its rows: each organization's name, address and when it was added. Use this when you have a List's id and need the organizations on it. |
| `export_list` | `GET /api/v1/lists/{id}/export.csv` | `lists:read` | A List's rows as a CSV file, the same file the app downloads. Use this when someone wants the whole List in a spreadsheet or another tool. |
| `create_list` | `POST /api/v1/lists` | `lists:write` | Make a new List, optionally with organizations on it. Send idempotencyKey (over REST, the Idempotency-Key header) so a retry makes one List, not two. Use this when someone asks to save a set of organizations. |
| `add_list_rows` | `POST /api/v1/lists/{id}/rows` | `lists:write` | Add organizations to a List by their ids, in one change. One already on the List is counted, not added twice. Use this when someone asks to put more organizations on a List. |
| `remove_list_rows` | `POST /api/v1/lists/{id}/rows` | `lists:write` | Take organizations off a List by their ids, in one change. The List's history keeps the earlier version. Use this when someone asks to remove organizations from a List. |
| `rename_list` | `PATCH /api/v1/lists/{id}` | `lists:write` | Give a List a new name. Nothing else about it changes. Use this when someone asks to rename a List. |
| `archive_list` | `POST /api/v1/lists/{id}/archive` | `lists:write` | Archive a List, which is how a List is deleted. It leaves every list view; the app can restore it. Use this when someone asks to delete or archive a List. |
| `my_steps` | `GET /api/v1/actions/steps` | `actions:read` | Steps across all your plans in one page, with the total: filter by status, due date and who owns them. Use this when someone asks what is due, late or blocked, without reading each plan. |
| `list_plans` | `GET /api/v1/actions/plans` | `actions:read` | Your action plans, newest change first, without their steps. Use this when you need a plan's id, or want to see which plans exist. |
| `read_plan` | `GET /api/v1/actions/plans/{id}` | `actions:read` | One action plan with every step: its status, owner, due date and why it is blocked. Use this when you have a plan's id and need its steps. |
| `set_step_status` | `POST /api/v1/actions/plans/{id}/steps/{stepId}/status` | `actions:write` | Move one step to a new status, such as done or blocked (blocked needs a reason). No version id is needed; it refuses only if that step changed first. Use this when someone finishes or is stuck on a step. |
| `create_plan` | `POST /api/v1/actions/plans` | `actions:write` | Make a new action plan with its steps. Send idempotencyKey (over REST, the Idempotency-Key header) so a retry makes one plan, not two. Use this when someone asks to plan the work for an account or a pursuit. |
| `edit_plan` | `PATCH /api/v1/actions/plans/{id}` | `actions:write` | Change a plan: add, edit, reorder or remove steps, or rename it, in one version. Send the version you read; a newer one is a conflict carrying it. Use this when someone asks to change a plan's steps. |
| `archive_plan` | `POST /api/v1/actions/plans/{id}/archive` | `actions:write` | Archive an action plan, which is how a plan is deleted; its steps leave every step list. Use this when someone asks to delete or archive a plan. |
| `list_drafts` | `GET /api/v1/drafts` | `drafts:read` | Your drafts, newest change first, without their text. Use this when you need a draft's id, or want to see which drafts exist or are approved. |
| `approved_drafts` | `GET /api/v1/drafts/approved` | `drafts:read` | Approved drafts with their full text, ready to send or import. Use this when moving approved emails, notes or briefs into another tool. |
| `read_draft` | `GET /api/v1/drafts/{id}` | `drafts:read` | One draft with its text, its evidence and whether it is approved. Use this when you have a draft's id and need what it says. |
| `create_draft` | `POST /api/v1/drafts` | `drafts:write` | Save a draft someone wrote, such as an email: its subject and body. It is recorded as their own text. Send idempotencyKey (over REST, the Idempotency-Key header) so a retry saves one draft. Use this when someone asks to keep a draft in HRC Ledger. |
| `edit_draft` | `PATCH /api/v1/drafts/{id}` | `drafts:write` | Change a draft's text or fields in one version. Send the version you read; a newer one is a conflict carrying it. Use this when someone asks to edit a saved draft. |
| `archive_draft` | `POST /api/v1/drafts/{id}/archive` | `drafts:write` | Archive a draft, which is how a draft is deleted. Use this when someone asks to delete or archive a draft. |
| `approve_review` | `POST /api/v1/reviews/{artifactId}/approve` | `drafts:approve` or `actions:approve` | Approve the version of a draft or plan you read, as the key's owner: a draft needs drafts:approve and a plan needs actions:approve. It never decides a change the assistant proposed; a person does that in the app. Use this when a person tells you to approve something under review. |
| `list_conversations` | `GET /api/v1/conversations` | `conversations:read` | Your conversations with the assistant, newest first, without their turns. Use this when you need a conversation's id, or want to find an earlier answer. |
| `read_conversation` | `GET /api/v1/conversations/{id}` | `conversations:read` | One conversation with its turns: each question, answer, the records it cited and the work it saved. Use this when you need what the assistant already said. |
| `rename_conversation` | `PATCH /api/v1/conversations/{id}` | `conversations:write` | Give a conversation a new title, or null to go back to its first question. Use this when someone asks to rename a conversation. |
| `delete_conversation` | `DELETE /api/v1/conversations/{id}` | `conversations:write` | Delete a conversation, as the app does: it leaves your list and its address stops opening. It answers 204 with no body, and deleting it twice is fine. Use this when someone asks to delete a conversation. |
| `read_memory` | `GET /api/v1/memory` | `memory:read` | What HRC Ledger knows about you and your company: the confirmed entries, each with where it came from and whether it was said or inferred, at most 200, with the total. Use this when you need the customer's ideal prospects, exclusions or tone. |
| `ask` | `POST /api/v1/ask` | `agent:ask` | Ask HRC Ledger's assistant a question; it reads the data and answers with its sources. It spends your plan's weekly usage. A long question answers with a run id: call get_run. Send idempotencyKey so a retry gets the first run. Use this when a question needs the assistant's reading. |
| `get_run` | `GET /api/v1/runs/{id}` | `agent:ask` | A run that ask started: still running with when to look again, or finished with its answer, sources and usage. It spends nothing. Use this when ask answered with a run id instead of an answer. |

<!-- END GENERATED: skill-operations -->

The contract and organization searches (`GET /api/v1/contracts`,
`GET /api/v1/contracts/{slug}`, `GET /api/v1/market/orgs`) and `POST /api/v1/ask` are
in the contract too.

## Connect over MCP

HRC Ledger is also an MCP server, at `https://hrcledger.com/api/mcp`, with the same key
in the same header. Ask the person before you add it to their agent. In Claude Code:

```sh
claude mcp add --transport http hrc https://hrcledger.com/api/mcp --header "Authorization: Bearer <your key>"
```

Put the key where it says `<your key>`, or ask the person to. The tools follow the
key's scopes; the guide is https://docs.hrcledger.com/developer/connect-your-agent.

## Read more

- Getting started: https://docs.hrcledger.com/developer/
- Keys and scopes: https://docs.hrcledger.com/developer/keys-and-scopes
- Connect your agent: https://docs.hrcledger.com/developer/connect-your-agent
- Errors: https://docs.hrcledger.com/developer/errors
- Pagination and versioning: https://docs.hrcledger.com/developer/pagination-and-versioning
- Changelog: https://docs.hrcledger.com/developer/changelog
- The contract: https://hrcledger.com/docs/api/openapi.json