Getting started

Paste this line into your coding agent, such as Claude Code or Cursor:

Add HRC Ledger to my app: hrcledger.com/SKILL.md

Your agent reads the steps. It asks you to make a key on the key page, then does the rest with you. You can also follow the steps below by hand.

Sign up at hrcledger.com. Keys work on every plan.

Go to Settings, API keys in the app. This is the only place a key is made.

A scope says what a key may do. Two scopes are ticked for you: contracts:read and market:read. They let a key search and read.

Tick more only when your code needs them. A key that can only read cannot change your work. Keys and scopes says what each scope allows.

Type a name, such as the app that will use it. Press Create key.

A key starts with hck_live_. You see the whole key one time only, so copy it now. Keep it in a secret store or an environment variable, never in your code.

export HRC_LEDGER_KEY="hck_live_..."

Send the key in the Authorization header. This call finds contracts:

curl -i -X GET \
  'https://hrcledger.com/api/v1/contracts?q=string&jurisdiction=string&buyerType=string&setAside=string&opportunityKind=string&personas=string&buyerClass=string&naics=string&psc=string&category=string&tag=string&type=string&recordType=string&status=open&minValue=0&maxValue=0&dueBefore=2019-08-24&dueAfter=2019-08-24&postedAfter=2019-08-24&firstSeenAfter=2019-08-24&window=string&commercialCategory=string&includePastDue=true&includeArchived=true&sort=relevance&page=0&limit=0' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

The reference has this sample in curl, JavaScript and Python for every route.

Every answer comes in one shape, called the envelope.

{ "ok": true, "data": [], "page": 1, "total": 0 }

When ok is true, your answer is in data. When ok is false, you get an error with a code and a message instead:

{ "ok": false, "error": { "code": "insufficient_scope", "message": "...", "scope": "lists:read" } }

Each answer also has an X-Request-Id header. Tell us that id if you ask for help with a call. Errors lists every code and what to do.

Tick agent:ask on a key to ask the HRC Ledger assistant a question.

curl -i -X POST \
  https://hrcledger.com/api/v1/ask \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "question": "Which Ohio hospitals changed EHR vendor this year?",
    "contract": "general"
  }'

The answer is in data.answer. The records it cites are in data.citations, each with a link when there is one. An ask uses the key's daily allowance; Keys and scopes says how much that is.

• Keys and scopes: what each scope allows, and how to revoke a key.
• Errors: every error code and what to do.
• Pagination and versioning: how to read long lists.
• Changelog: what changed, and when.