# Changelog and versioning What changed in the HeadHoncho API and when, and the promise that v1 keeps working as documented. Page: https://headhoncho.app/docs/api/changelog | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json | Everything in one file: https://headhoncho.app/docs/api/llms-full.txt ## The promise: v1 does not break Every address on this site starts with `/api/v1`. That `v1` is a promise. Code that works against v1 today keeps working. ## What we will not do in v1 - Remove or rename an endpoint, a parameter, an answer field or an error code. - Change what a field, a parameter or an error code means, or its type. - Make an optional parameter required. - Change who may call an endpoint to make it stricter for a key that could before. ## What we may do in v1 - Add endpoints, groups and MCP tools. - Add optional parameters, and new fields to an answer. Ignore fields you do not know: your code should not fail on them. - Add values to a list of choices, such as a new status or method. Do not fail on a value you have not seen. - Add error codes. Branch on the codes you know and treat any other as a failure of its HTTP status class. - Fix a bug so that the API does what its page already said. ## If something has to break A change that would break v1 ships as a new version, `/api/v2`, beside it. The notice goes on this page first, and v1 keeps its documented behaviour until then. Nothing changes for your code unless you move it. Each change is listed here with its date, newest first. The reference pages are always the current truth; this page says when it moved. ## What changed ### 2026-10-28: Keys and webhooks on every plan - API keys and webhooks come with every plan now, Free included. Calls still cost a credit each, and a change delivered still costs one credit. ### 2026-10-27: Webhooks: we call your address when a job changes - Webhooks: give us an address and the kinds of change you want, and we send each one as a signed `POST`, retried for 24 hours. A guide shows how to check the signature in cURL, Python and JavaScript. - Eight new calls: add, change, list, get and remove a webhook, send a test event, list a webhook's deliveries and send one again. - One credit per change delivered, however many tries it takes. Webhooks come with Core and up, like keys. ### 2026-10-26: Jobs from start to finish, job money, and credits instead of limits - Jobs have their whole life: change a job, move it between statuses, assign and take off technicians, add, change and remove notes, archive and unarchive, move to Trash and restore. - Job money: read what a job quoted, collected and left as profit; record and void payments and expenses; set a technician's cut; manage expense types. - Balances: see what each technician is owed, read a statement, close a balance, and record or void a payout. - Field reports: list what technicians reported and book or dismiss each one. - There is no rate limit. Each answered call costs 1 credit; a refusal costs nothing. Answers carry `X-HH-Credits-Charged`, `X-HH-Credits-Left` and `X-Request-Id`. At zero credits a call is refused with `no_credits`. - MCP tools that change something take an optional `idempotency_key`. Tools that take something out of the books or out of sight are marked destructive. - MCP tool answers start with a one-line summary, then the full answer, and carry the answer as structured content. The reference, the guides and the error catalog can be read as MCP resources. - The docs gained a table of every field in each answer, a try-it box that builds your call, search, recipes, a page for coding agents and this changelog. - Account: list your companies and read one, your usage, your credits and the plans. - Changes: a feed of what changed on your jobs since a cursor, and the list of change types. - Jobs: photos, the calendar, unscheduled jobs, a jobs file, search, and where a status, a detour or a hand-off stands. - Job commands: back to automatic, resolve a detour, upload and delete a photo. - Many jobs at once: status, assign, unassign, note, archive, unarchive, Trash and restore, up to 200 jobs a call. - Clients: list, read, create, change and delete the people jobs are for. - Leads: list and read leads, send one in, change it, book it as a job, mark it lost, pass on it or dismiss it, review a conversion, and schedule, change, resolve or cancel follow-ups. What needs a person, as a list of jobs and why. - Team: list technicians, read one, add one and change one. - Statistics and marketing: booked jobs and profit for a range, jobs by area, map pins, ad accounts, campaigns and the agency jobs feed. - Company settings: read them, change a company and the workspace, job types, statuses and the status line, and syncs for CallRail and the ad platforms. - Imports: bring jobs over from another system: stage a file, match statuses and job types, preview, rehearse and commit. ### 2026-10-14: The starter - The API opened with sixteen endpoints in five groups: Account, Jobs, Job commands, Raw data, and Click IDs and conversions. - Reads are `GET` over the records the app draws. Commands are `POST` to `/commands/` with an `Idempotency-Key`. - Keys are made in the app, with companies and access per area. Missing something you need? Tell [support](https://headhoncho.app/support). The plan for what comes next is on [the roadmap](https://headhoncho.app/docs/api/roadmap).