Whoami

The request

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

GET /api/v1/whoami

Any key or connected app can call it. It counts as a read call: 300 a minute for each key or connected app. See rate limits.

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

Parameters

This call takes no parameters.

What comes back

The workspace, the credential, the companies it may name, its access per area, and the lookups a command needs: every status, job type and technician, with ids. Lookups are carried here so a client never has to guess a name.

It never changes a record. It only reads the companies the key reaches.

Call this first

Everything a command needs by id is here: the company, the status, the job type, the technician. A name works too where the docs say so, and the answer tells you which name it understood.

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.
`expired_token`	401	That token has expired. Refresh it, or connect the app again.
`rate_limited`	429	Too many calls this minute. Wait and try again.

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

Answer cURL Python JavaScript Your AI

{
  "workspace": {
    "id": "org_2c7d",
    "name": "Northwind Ads"
  },
  "credential": {
    "kind": "key",
    "name": "Reporting laptop",
    "acts_as": "Ariel T.",
    "hide_personal_details": false
  },
  "companies": [
    {
      "id": "cmp_14f5",
      "name": "Sunrise Moving",
      "time_zone": "America/Chicago"
    },
    {
      "id": "cmp_8a21",
      "name": "Capital Roofing",
      "time_zone": "America/New_York"
    }
  ],
  "access": {
    "jobs": "do",
    "raw": "read",
    "conv": "read"
  },
  "statuses": [
    {
      "id": "st_01",
      "name": "Draft",
      "slug": "draft"
    },
    {
      "id": "st_02",
      "name": "Scheduled",
      "slug": "scheduled"
    },
    {
      "id": "st_03",
      "name": "Dispatched",
      "slug": "dispatched"
    },
    {
      "id": "st_06",
      "name": "Closed",
      "slug": "closed"
    }
  ],
  "job_types": [
    {
      "id": "jt_02",
      "name": "Local move"
    },
    {
      "id": "jt_05",
      "name": "Roof repair"
    }
  ],
  "technicians": [
    {
      "id": "wrk_3b90",
      "name": "Dana R.",
      "role": "technician"
    },
    {
      "id": "wrk_7a12",
      "name": "Omar S.",
      "role": "subcontractor"
    }
  ]
}

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

import requests

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

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

Tool: whoami
Arguments: none
Access: any key or approved app
Hints: readOnly=true, destructive=false, idempotent=true, openWorld=false
Try asking: "Using HeadHoncho, whoami."

The request

Parameters

What comes back

Call this first

Errors that apply

Related