The request
Reference for List plans, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.
GET /api/v1/plans
Any key can call it. An answered call costs 1 credit; a refusal costs nothing. See credits.
Send your key as Authorization: Bearer hh_live_.... See API keys.
Parameters
This call takes no parameters.
Try it with your key
Paste your key and change the values. The box builds the call as a cURL line and a fetch line, ready to copy. It never sends anything itself.
Your key stays in this page and is never sent anywhere. Copy the line below and run it yourself.
What comes back
plans, in the order the app prints them: code, name, monthly_price_cents (null when you must talk to us), self_serve, is_recommended, entitlements (unit_code, unit_name, included, unlimited, custom), the extra credit pack if the plan has one, history_months, scheduled_reports and api_access. every_plan: what is unlimited on all of them. current: the plan in force. pack: the credit pack this workspace may buy, or null.
It never changes a record. It only reads the companies the key reaches.
Every field in the answer
Types are read from the example answer. Money is a plain number in the company's currency. A time carries its offset from UTC (Z is UTC). Ids are opaque text. A field with no line of its own here has its name spelled out; the common fields mean the same on every page.
| Field | Type | Meaning |
|---|---|---|
plans | list of objects | The plans. |
plans[].code | text | The code. |
plans[].name | text | The name, as the app shows it. |
plans[].monthly_price_cents | whole number | The monthly price cents. |
plans[].self_serve | true or false | The self serve. |
plans[].is_recommended | true or false | True when it is recommended. |
plans[].entitlements | list of objects | The entitlements. |
plans[].entitlements[].unit_code | text | The unit code. |
plans[].entitlements[].unit_name | text | The unit name. |
plans[].entitlements[].included | whole number | The included. |
plans[].entitlements[].unlimited | true or false | The unlimited. |
plans[].entitlements[].custom | true or false | The custom. |
plans[].pack | value or null | The pack. |
plans[].history_months | whole number | The history months. |
plans[].scheduled_reports | true or false | The scheduled reports. |
plans[].api_access | true or false | The api access. |
every_plan | list of objects | The every plan. |
every_plan[].unit_code | text | The unit code. |
every_plan[].unit_name | text | The unit name. |
current | object | The current. |
current.code | text | The code. |
current.name | text | The name, as the app shows it. |
current.status | text | The job status. |
pack | value or null | The pack. |
Errors that apply
| Code | Status | What it means |
|---|---|---|
| `missing_key` | 401 | Send your key as Authorization: Bearer hh_live_... |
| `unknown_key` | 401 | That key is not one we issued, or it was revoked. |
| `no_credits` | 402 | Out of credits. Top up on Settings › Credits, or turn on auto top-up. |
Related
- Whoami: Who this key or app acts as, which companies it reaches, what it may do, and the words to use in commands: statuses, job types and technicians.
- List companies: The companies this credential reaches, each with its name, time zone, country and service area. The same ids every other call takes as company_id.
- Get company: One company this credential reaches: its name, time zone, country and service area.
- Get usage: What the plan has used, what API calls cost and what this credential called, by day or by endpoint, with the credits left.
- Get credits: This month's credits: the plan's grant, what rolled over, what was bought, what was used and what is left.
- The same records in the app: Multiple companies.
- How the API fits together: the model, API keys, errors and the MCP server.