{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-developer/sidebars.yaml","api-docs-docs/openapi.json":"api-docs-docs/openapi.json"},"props":{"metadata":{"markdoc":{"tagList":["openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Getting started","description":"Read US healthcare contracts and organizations, and work with your saved work, from your own code.","siteUrl":"https://docs.hrcledger.com","llmstxt":{"title":"HRC Ledger API","description":"One key, one envelope, every route and guide."}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"getting-started","__idx":0},"children":["Getting started"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Paste this line into your coding agent, such as Claude Code or Cursor:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"Add HRC Ledger to my app: hrcledger.com/SKILL.md\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"1-make-an-account","__idx":1},"children":["1. Make an account"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sign up at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://hrcledger.com/sign-up"},"children":["hrcledger.com"]},". Keys work on every plan."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"2-open-the-key-page","__idx":2},"children":["2. Open the key page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Go to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://hrcledger.com/settings/api-keys"},"children":["Settings, API keys"]}," in the app."," ","This is the only place a key is made."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"3-choose-the-scopes","__idx":3},"children":["3. Choose the scopes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A scope says what a key may do. Two scopes are ticked for you:"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["contracts:read"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["market:read"]},". They let a key search and read."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tick more only when your code needs them. A key that can only read cannot change"," ","your work. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer/keys-and-scopes"},"children":["Keys and scopes"]}," says what each scope allows."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"4-make-the-key-and-keep-it-safe","__idx":4},"children":["4. Make the key and keep it safe"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Type a name, such as the app that will use it. Press ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Create key"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A key starts with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"export HRC_LEDGER_KEY=\"hck_live_...\"\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"5-make-your-first-call","__idx":5},"children":["5. Make your first call"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Send the key in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Authorization"]}," header. This call finds contracts:"]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"api-docs-docs/openapi.json","operationId":"listContracts","language":"curl","parameters":{},"environments":{},"codeSamplesResolved":[{"lang":"shell","title":"curl","source":"curl -i -X GET \\\n  https://hrcledger.com/api/v1/contracts \\\n  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'"}]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/openapi"},"children":["reference"]}," has this sample in curl, JavaScript and Python"," ","for every route."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"6-read-the-answer","__idx":6},"children":["6. Read the answer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every answer comes in one shape, called the envelope."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"ok\": true, \"data\": [], \"page\": 1, \"total\": 0 }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ok"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},", your answer is in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},". When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ok"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},", you get an"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["error"]}," with a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," instead:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{ \"ok\": false, \"error\": { \"code\": \"insufficient_scope\", \"message\": \"...\", \"scope\": \"lists:read\" } }\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each answer also has an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["X-Request-Id"]}," header. Tell us that id if you ask for help"," ","with a call. ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer/errors"},"children":["Errors"]}," lists every code and what to do."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"7-ask-the-assistant","__idx":7},"children":["7. Ask the assistant"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tick ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["agent:ask"]}," on a key to ask the HRC Ledger assistant a question."]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"api-docs-docs/openapi.json","operationId":"ask","language":"curl","parameters":{},"environments":{},"codeSamplesResolved":[{"lang":"shell","title":"curl","source":"curl -i -X POST \\\n  https://hrcledger.com/api/v1/ask \\\n  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n    \"question\": \"Which Ohio hospitals changed EHR vendor this year?\",\n    \"contract\": \"general\"\n  }'"}]},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The answer is in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.answer"]},". The records it cites are in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data.citations"]},", each"," ","with a link when there is one. An ask uses the key's daily allowance;"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer/keys-and-scopes"},"children":["Keys and scopes"]}," says how much that is."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"next","__idx":8},"children":["Next"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer/keys-and-scopes"},"children":["Keys and scopes"]},": what each scope allows, and how to revoke a key."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer/errors"},"children":["Errors"]},": every error code and what to do."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer/pagination-and-versioning"},"children":["Pagination and versioning"]},": how to read long lists."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/developer/changelog"},"children":["Changelog"]},": what changed, and when."]}]}]},"headings":[{"value":"Getting started","id":"getting-started","depth":1},{"value":"1. Make an account","id":"1-make-an-account","depth":2},{"value":"2. Open the key page","id":"2-open-the-key-page","depth":2},{"value":"3. Choose the scopes","id":"3-choose-the-scopes","depth":2},{"value":"4. Make the key and keep it safe","id":"4-make-the-key-and-keep-it-safe","depth":2},{"value":"5. Make your first call","id":"5-make-your-first-call","depth":2},{"value":"6. Read the answer","id":"6-read-the-answer","depth":2},{"value":"7. Ask the assistant","id":"7-ask-the-assistant","depth":2},{"value":"Next","id":"next","depth":2}],"frontmatter":{"seo":{"title":"Getting started"}},"lastModified":"2026-10-22T07:39:08.493Z","pagePropGetterError":{"message":"","name":""}},"slug":"/developer","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}