# Whoami

Whoami is a read in the HeadHoncho API. 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.

Page: https://headhoncho.app/docs/api/whoami | Part of the HeadHoncho API docs: https://headhoncho.app/docs/api | Machine-readable: https://headhoncho.app/docs/api/openapi.json

## 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](https://headhoncho.app/docs/api/errors#rate-limits).

Send your key as `Authorization: Bearer hh_live_...`. See [API keys](https://headhoncho.app/docs/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`](https://headhoncho.app/docs/api/errors#missing_key) | 401 | Send your key as Authorization: Bearer hh_live_... |
| [`unknown_key`](https://headhoncho.app/docs/api/errors#unknown_key) | 401 | That key is not one we issued, or it was revoked. |
| [`expired_token`](https://headhoncho.app/docs/api/errors#expired_token) | 401 | That token has expired. Refresh it, or connect the app again. |
| [`rate_limited`](https://headhoncho.app/docs/api/errors#rate_limited) | 429 | Too many calls this minute. Wait and try again. |

## Related

- The same records in the app: [Multiple companies](https://headhoncho.app/docs/companies).
- How the API fits together: [the model](https://headhoncho.app/docs/api/model), [API keys](https://headhoncho.app/docs/api/keys), [errors](https://headhoncho.app/docs/api/errors) and [the MCP server](https://headhoncho.app/docs/api/mcp).

## Examples

### Answer

```json
{
  "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

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

### Python

```python
import requests

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

### JavaScript

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

### Your AI

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