Skip to content

The HeadHoncho public API

The HeadHoncho public API lets your code, or the AI app you already use, read a client's jobs and raw ad data and change jobs, under the same rules as the app.

Read as Markdown

What the API is

The HeadHoncho public API is the app, reachable from code. It gives a marketing agency's campaigner, or the developer they hired, the same records the app draws: jobs and leads, the raw rows each ad platform and call tracker reported, and the Google Click ID report. An AI app can use it too, through the MCP server.

It follows the app's own model. A read is a GET over a record the app already shows. A change is a POST to /api/v1/commands/<verb>, where the verb is the app's own command name. Nothing is computed here that the app does not compute. The longer version is on the model.

There are 16 endpoints in 5 groups today, all under https://api.headhoncho.app/api/v1. It gives you building blocks: records, raw rows and single commands. It never gives you a board, a dashboard or an automation to rebuild the app with. The roadmap says what is planned and what will never be offered.

The 5 groups

Account

  • 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.

Jobs

  • List jobs: Jobs and leads in the companies this credential reaches, newest first, with status, technician, schedule, money and the ad click each came from.
  • Get job: One job or lead: who, where, when, which status, which technicians, the money on it and the ad click it came from.
  • Get job history: Everything that happened to a job, in order, with who did it: created, moved, assigned, noted, paid. The same log the job page shows.

Job commands

  • Create job: Open a job or a lead in one company: the customer, the address, and optionally the job type, the time window and the technician.
  • Update job: Change a job's facts: the customer, the address, the schedule, the price, the job type or the notes. Only the fields you send change.
  • Change job status: Move a job to another status by its name, slug or id. The move lands in the job's history with who asked for it.
  • Assign worker: Put a technician or subcontractor on a job. If Job follow-up is on, the automation acts on it at once, as it would from the app.
  • Unassign worker: Take a technician or subcontractor off a job. The ticket's cancellation reaches them the way it does from the app.
  • Add job note: Add a note to a job. It appends to the job's log and never overwrites.

Raw data

  • List tables: Every raw table, by the provider that produced it, with its columns, its grain and whether this company has it connected.
  • Read table: Rows of one raw table for one company and a date range, exactly as the provider reported them. No joins, no derived figures.
  • Export table: One raw table as a CSV file for a company and a date range, up to 50,000 rows, with its caveat in the last lines.

Click IDs and conversions

  • Get job conversion: What this job told the ad platform it was worth: the click it came from, each conversion sent, its value and its basis, and what Google did with it.
  • Get click id report: The Google Click ID report: one row per job that opened or closed in the range, with its click id, its tracked call, its total and its profit.
  • Export click id report: The Google Click ID report as a file: the agency's sheet, or the Google Ads offline conversion upload file, ready to upload.

Get a key

Make a key in the app at Automations, then API keys. Choose the companies it reaches, the access it has per area, and whether personal details are hidden. The key is shown once. The full walk-through is on API keys.

Then make your first call. It tells you who the key acts as, which companies it reaches and the statuses, job types and technicians to use in commands:

curl "https://api.headhoncho.app/api/v1/whoami" \
-H "Authorization: Bearer hh_live_..."

The answer is shown on Whoami.

Connect an AI app

Claude, ChatGPT, Claude Code and Cursor can use the same 16 endpoints as tools, with the same names and arguments. Paste https://api.headhoncho.app/mcp into the app's connector settings, or pass a key. Setup for each app is on the MCP server. An AI app only ever reaches the companies and areas you approve.

The same records in the app

Everything the API returns is something the app already shows. The Jobs panel draws the jobs. The Raw data board draws the raw rows. Offline conversion tracking explains why the click id matters. Multiple companies explains how one login holds many client businesses, which is what a key's company list is made of.

What is coming

A group of endpoints arrives when the owner approves it, and an endpoint is never built without appearing on the roadmap first.

Machine-readable copies

No credit card required.Try it free