Halcyon API: Getting Started Guide

What is the Halcyon API?

The Halcyon API gives you programmatic access to the same regulatory documents, dockets, AI-powered queries, and Data Subscriptions currently available via Halcyon’s platform. Instead of clicking through the app, you can search, query, and download data directly from your own agents, code, scripts, spreadsheets, and tools.

The API is currently in limited beta for paid Halcyon customers. It is a REST API served at https://api.halcyon.io/v1, authenticated with a personal API key, and fully documented at api.halcyon.io.

Common ways customers use Halcyon’s API:

Let Claude, Codex, or another AI assistant search and query Halcyon on your behalf, iterating on search constraints far faster than you could by hand

Run hundreds of queries across dockets in a coding or research session

Pull Data Subscriptions (like the Large Load Tariff Tracker) into Snowflake, Databricks, Power BI, or a CRM on a schedule

Enrich internal records (utility profiles, project trackers) with information from filings

Build monitoring and alerting into your own dashboards and workflows

Getting access

API access is enabled per organization by the Halcyon team. If your organization has API access, every user who is a member of that organization can create their own API key. If you're not sure whether your organization has access, contact your Halcyon account manager or request access through the form linked at the top of api.halcyon.io.

Your API key sees exactly what you see in the platform. Permissions through the API mirror your platform permissions: if you can view a document, docket, or Data Subscription in the Halcyon app, you can access it through the API. If you can't download a Data Subscription in-app, you won't be able to download it via the API either. The API is a different surface for the same access, not a way to unlock additional content.

This also means each person should use their own key. Keys are tied to your user and account, and activity under a key is attributed to you.

Creating your API key

Log in to Halcyon, press on your avatar on the top right hand side of the screen, and go to API Keys: app.halcyon.io/user/preferences/api-keys.

Click Create key and give it a descriptive name (for example, claude-research or databricks-sync) so you can tell keys apart later.

Copy the key immediately and store it somewhere safe. Keys are shown in full only once.

Keep your key secret. Anyone with your key can search, query, and download data as you. Treat it like a password:

Never paste a key into a shared document, chat channel, or code repository.

If you use a key in a one-off AI assistant session, delete it from the API Keys page when you're done and create a fresh one next time.

Create separate keys for separate tools so you can revoke one without breaking the others.

If a key is exposed, delete it right away from the API Keys page. Deletion takes effect immediately.

Checking that your key works

Every request to the API includes your key in a header called X-API-Key. The quickest way to confirm a key is valid is to call the ping endpoint (POST https://api.halcyon.io/v1/ping) with that header. If the key is good, the API echoes back the account and user it belongs to. If you use an AI assistant, just ask it to "call ping to confirm the key works" as the first step.

If ping fails, check that you copied the full key, that it hasn't been deleted, and that your organization has API access enabled.

What you can do with the API

The current API capabilities are listed below. The full reference, with every field explained, is at api.halcyon.io.

Area	What it lets you do
Identity	Confirm a key works and see which account it belongs to
Constraints	Look up the publishers, filing types, and topics you can filter on
Search	Find documents or dockets that match your filters and get their metadata (title, publisher, date, filing type). Optionally include AI-generated document summaries
Queries	Ask a natural-language question over a filtered set of documents and get a cited answer, either as text or as structured data you define
Alerts (read-only)	List your alerts, see the schedule and query behind each one, and read the notifications they’re delivered, including which documents were found and what the queries answered. Note: You can’t create or edit alerts through the API yet.
Data Subscriptions	List the data products you're subscribed to, read their change logs, and download the latest release as an Excel file

Filters work the same way everywhere: you can narrow by publisher, filing type, topic, docket, document, date range, or exact phrases, and combine them with AND, OR, and NOT.

How to get good answers: narrow first, then ask

The API works best when you narrow down the documents first and ask your question second. A query reads a bounded, ranked selection of the matching documents, not every single match. If your filters match thousands of documents, the answer may be incomplete without any warning. Keeping the matched set small is what keeps answers accurate.

Find your filter values. Look up the publisher, filing type, or topic you need. To work with a specific docket, search dockets by publisher and docket number to get its Halcyon ID.

Search and check the count. Run a search with your filters and look at the approximate total count. Tighten the filters (add a date range, a docket, a filing type, or an exact phrase) until the set is small enough to read in full.

Create and run your query. Create a query with your question and the same filters, then run it. You'll get an answer with citations to specific documents and pages. If you want a table or other structured result, describe the shape you want and the answer comes back in that format.

Follow the citations. Each citation points to a document id. Look those up to get titles, publishers, dates, and links back to the documents in Halcyon.

Downloading a Data Subscription takes two steps: list your data subscriptions to find the one you want (only products marked as subscribed are downloadable), then download its latest release. You don't need to know the version number, and the change log shows what changed between releases.

Using the API with Claude, Codex, or another AI assistant

Some customers use the API through an AI assistant rather than writing code. Halcyon can take a few rounds of tweaking filters to land on the right dockets, and letting an assistant do that iteration for you means you can cover far more ground in a session. The setup is the same for Claude (web, desktop, or Claude Code), OpenAI Codex, Google Antigravity, and similar tools.

Create a fresh API key at app.halcyon.io/user/preferences/api-keys. You'll delete it when you're done.

Save the API spec from api.halcyon.io/openapi.json as a file on your computer.

Start a new chat, attach the spec file, and paste a prompt like this with your key filled in:

I'm giving you a temporary API key to the Halcyon Public API, which I will delete after this session. Key: sk_your_key_here. I've attached the API spec. Start by calling ping to confirm the key works, then: [your task, for example "find the 10 most recent filings from the Minnesota PUC and summarize them in a few sentences"]

Work with the assistant as usual. Good tasks include finding dockets that match a set of criteria, running the same question across many dockets and tabulating the results, pulling a Data Subscription and analyzing it, or building a small tool on top of the API.

When you're finished, delete the key on the API Keys page.

A few things help: ask the assistant to check the match count before running a query and to split broad questions into narrower ones; ask it to look up citations so you get links back to the source documents; and spot-check answers against those documents for anything high-stakes. Assistants produce polished output quickly, but they also make assumptions.

If your company restricts which websites your AI assistant can reach, api.halcyon.io needs to be on the allowed list. If the assistant says it can't reach that address, ask your IT administrator to add it.

IMPORTANT: AI assistants can hallucinate. Halcyon does not guarantee information fidelity when its platform is accessed via LLMs or other agentic AI-based mechanisms.

Tips

Narrow before you query. This is the biggest driver of answer quality. If a question spans many dockets, run it once per docket and combine the results rather than asking one broad question.

Expect some variability in speed. A typical query takes a few seconds, but some take noticeably longer and an occasional request may fail. If you're running many queries in a script, add retries and run requests in parallel rather than one at a time.

Ask for structured output when you want a table. Describe the fields you want and the answer comes back as data you can drop into a spreadsheet, with a citation on every value.

Use exact phrases for known identifiers. Phrase filters are a reliable way to pin down a docket number, project name, or company across documents.

Your API queries currently show up in the app. Anything you run through the API appears on your Queries page, so you can revisit results in the platform. If the list gets long, you can delete queries through the API.

Re-read instead of re-running. If you just want to see a result again, fetch the query's saved response rather than running it a second time.

Current limitations and what's coming

The API is in beta, so the scope is deliberately focused:

No full-document download. You get document metadata, AI-generated summaries, and cited answers with page numbers, but not the full text or original file. For work where every word matters, follow the citation links to read the source in the Halcyon app.

Answers aren't strictly repeatable. Due to the non-deterministic nature of LLMs, the same question can produce slightly different answers on different runs. Narrower filters reduce, but will not always exclusively prevent, this.

Match counts are estimates, not exact figures.

Filing type may be blank for some documents where the publisher doesn't supply it.

Grids, and Projects aren't available through the API yet. Read access to Grids is the next planned expansion.

Webhooks (pushing new results into tools like Salesforce) aren't supported yet.

We're expanding the API based on beta feedback. If there's something you need, tell your account manager or email support@halcyon.io.

Troubleshooting

Problem	What to do
Ping says the key is invalid	Re-copy the full key from the API Keys page, or create a new one. If it still fails, your organization may not have API access yet; check with your account manager
Your AI assistant can't reach api.halcyon.io	Your company likely restricts which sites the assistant can visit. Ask IT to allow api.halcyon.io. If it's already allowed, wait 10–15 minutes and try again; this has occasionally been a temporary gateway hiccup
A Data Subscription is missing or not downloadable	API access mirrors your platform access. Ask your account manager to add the subscription if you feel you should be able to access it.
A query returns no results	Loosen your filters, or run a search with the same filters to see what matches
An answer seems incomplete	Your filters matched too many documents. Narrow them, or split the question into several smaller queries
A script running many queries is slow or fails partway	Add retries, allow longer timeouts, and run requests in parallel
The same query gives different answers	Narrow filters can help, but will not explicitly prevent this (LLM technology is non-deterministic).

Still stuck? Email support@halcyon.io with what you were trying to do, roughly when, and the error you saw. Never include your API key.

FAQ

Is the API included in my subscription? It's in limited beta for paid customers by arrangement with your account team. Pricing for general availability is being finalized.

Does the API give me access to more data than the platform? No. It's another way to reach exactly the content your account already has.

Can I download the original documents? Not at this time. You get metadata (for example, a filing’s title, publisher, date, filing type, docket, and page count), AI-summaries, and cited answers with page numbers, plus links into the Halcyon app to read the full source.

Can I get my Alerts or Grids through the API? Alerts, yes: you can list your alerts and read their notifications (read-only)/ Grids are the next planned expansion.

Is there an MCP server or Claude connector? Not yet. For now, give your assistant a temporary key and the spec file as described above. We're exploring an MCP to make this simpler.

Can my team share one key? Please don't. Each person should create their own so activity is attributable and access can be revoked individually.

Where are the docs? api.halcyon.io.

Got questions or feedback about this page? support@halcyon.io