Get settings

The request

Reference for Get settings, HeadHoncho API v1. It is a read, sent to the base address https://api.headhoncho.app.

GET /api/v1/settings

The key needs the Company settings area at read. An answered call costs 1 credit; a refusal costs nothing. See credits.

Send your key as Authorization: Bearer hh_live_.... See API keys.

Parameters

Name	Kind	Required	Description	Example
`company_id`	id, in the query	No	One company. Default: every company the credential reaches.	`cmp_14f5`

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 API key company_id (optional, id)

Your key stays in this page and is never sent anywhere. Copy the line below and run it yourself.

What comes back

organization (id, name). companies, one per company: id, name, status, service_area, time_zone, country, week_start and week_end (0 is Monday), color, has_logo, business_hours (weekday, opens, closes) and service_places (city, state). job_types and statuses are shared by every company: each status has its slug, tone, colors, icon, band (line or detour), position, archived and job_count, the jobs on it in the companies this credential reaches. status_icons lists the marks a status may wear.

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
`organization`	object	The organization.
`organization.id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`organization.name`	text	The name, as the app shows it.
`companies`	list of objects	The companies.
`companies[].id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`companies[].name`	text	The name, as the app shows it.
`companies[].status`	text	The job status.
`companies[].service_area`	text	The service area.
`companies[].time_zone`	text	The company's time zone name, such as America/Chicago.
`companies[].country`	text	The country.
`companies[].week_start`	whole number	The week start.
`companies[].week_end`	whole number	The week end.
`companies[].color`	text	The color.
`companies[].has_logo`	true or false	True when there is a logo.
`companies[].business_hours`	list of objects	The business hours.
`companies[].business_hours[].weekday`	whole number	The weekday.
`companies[].business_hours[].opens`	text	The opens.
`companies[].business_hours[].closes`	text	The closes.
`companies[].service_places`	list of objects	The service places.
`companies[].service_places[].city`	text	The city.
`companies[].service_places[].state`	text	The state or region.
`job_types`	list of objects	The job types.
`job_types[].id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`job_types[].name`	text	The name, as the app shows it.
`job_types[].position`	whole number	Where the change landed in the event log. Pass it as `after` on a read to see your own write.
`job_types[].archived`	true or false	The archived.
`statuses`	list of objects	The statuses.
`statuses[].id`	id (text)	The id of this record. Ids are opaque text: keep them exactly as given.
`statuses[].name`	text	The name, as the app shows it.
`statuses[].slug`	text	The same name as a lowercase code word. Match on this, not on the name.
`statuses[].tone`	text	The tone.
`statuses[].color`	text	The color.
`statuses[].ink`	text	The ink.
`statuses[].icon`	text	The icon.
`statuses[].band`	text	The band.
`statuses[].position`	whole number	Where the change landed in the event log. Pass it as `after` on a read to see your own write.
`statuses[].archived`	true or false	The archived.
`statuses[].job_count`	whole number	The job count.
`status_icons`	list of text	The status icons.

Shared by every company

Job types and statuses belong to the workspace, not to one company. The same list is returned whichever company you ask for.

Counts

job_count leaves out Trash and jobs in companies this credential does not reach.

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_access`	403	This credential does not reach that. Ask the person who made it for access.
`not_found`	404	No such record in the companies this credential reaches.
`out_of_scope`	404	No such company in the companies this credential reaches.
`invalid`	422	Some fields were refused. See fields.
`no_credits`	402	Out of credits. Top up on Settings › Credits, or turn on auto top-up.

The same records in the app: Settings.
How the API fits together: the model, API keys, errors and the MCP server.

Answer cURL Python JavaScript Your AI

{
  "organization": {
    "id": "org_2c7d",
    "name": "Northwind Ads"
  },
  "companies": [
    {
      "id": "cmp_14f5",
      "name": "Sunrise Moving",
      "status": "active",
      "service_area": "Bloomington and Normal, IL",
      "time_zone": "America/Chicago",
      "country": "US",
      "week_start": 0,
      "week_end": 6,
      "color": "#2f6fdb",
      "has_logo": false,
      "business_hours": [
        {
          "weekday": 0,
          "opens": "08:00:00",
          "closes": "17:00:00"
        },
        {
          "weekday": 1,
          "opens": "08:00:00",
          "closes": "17:00:00"
        }
      ],
      "service_places": [
        {
          "city": "Bloomington",
          "state": "IL"
        },
        {
          "city": "Normal",
          "state": "IL"
        }
      ]
    }
  ],
  "job_types": [
    {
      "id": "jt_02",
      "name": "Local move",
      "position": 0,
      "archived": false
    },
    {
      "id": "jt_05",
      "name": "Packing only",
      "position": 1,
      "archived": false
    }
  ],
  "statuses": [
    {
      "id": "st_01",
      "name": "Draft",
      "slug": "draft",
      "tone": "neutral",
      "color": "",
      "ink": "",
      "icon": "",
      "band": "line",
      "position": 0,
      "archived": false,
      "job_count": 12
    },
    {
      "id": "st_02",
      "name": "Scheduled",
      "slug": "submitted",
      "tone": "info",
      "color": "",
      "ink": "",
      "icon": "",
      "band": "line",
      "position": 1,
      "archived": false,
      "job_count": 31
    },
    {
      "id": "st_09",
      "name": "Waiting",
      "slug": "",
      "tone": "warn",
      "color": "#f2c94c",
      "ink": "#3a2f00",
      "icon": "pause",
      "band": "detour",
      "position": 7,
      "archived": false,
      "job_count": 4
    }
  ],
  "status_icons": [
    "alarm",
    "schedule",
    "call",
    "chat",
    "warning",
    "gavel",
    "help",
    "pause",
    "person",
    "construction",
    "payments"
  ]
}

curl "https://api.headhoncho.app/api/v1/settings?company_id=cmp_14f5" \
  -H "Authorization: Bearer hh_live_..."

import requests

response = requests.get(
    "https://api.headhoncho.app/api/v1/settings",
    headers={"Authorization": "Bearer hh_live_..."},
    params={
        "company_id": "cmp_14f5",
    },
)
response.raise_for_status()
print(response.json())

const response = await fetch("https://api.headhoncho.app/api/v1/settings?company_id=cmp_14f5", {
  headers: { Authorization: "Bearer hh_live_..." },
});
const data = await response.json();
console.log(data);

Tool: get_settings
Arguments: company_id (id, optional)
Access: read on Company settings
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, get settings with company_id cmp_14f5."