# HMU API — Full Reference

> HMU API is a multi-tenant inbox platform. Each user gets one URL with structured channels for every type of inbound message — deals, meetings, questions, hiring, press, and more. Messages arrive pre-classified and AI-scored, replacing the unstructured chaos of email.
>
> Email is human-to-human. HMU API is anything-to-human.
>
> Base URL: https://hmuapi.com/api (also accessible via https://hitmyapi.com)
> Rate limit: 10 per sender per endpoint per 30 days.
> All POST submission endpoints return: { "success": true, "message_id": "uuid", "token": "uuid", "auto_response": "..." }

## Agent Discovery Flow

Any LLM, agent framework, or automation tool that makes HTTP requests can integrate with HMU API. No API key needed for public endpoints.

### Step 1: Discover the user
```
GET /api/u/:username
```
Returns: display name, bio, active channels, preferences.

### Step 2: Read available channels
```
GET /api/u/:username/endpoints
```
Returns: list of active channels with field schemas and descriptions.

### Step 3: Submit a message
```
POST /api/u/:username/:endpoint
Content-Type: application/json

{
  "name": "Agent Name",
  "email": "agent@example.com",
  "question": "What technologies are you currently exploring?"
}
```
Returns: `{ "success": true, "message_id": "uuid", "token": "uuid" }`

### Step 4: Track delivery
```
GET /api/status/:token
```
Returns: `{ "status": "received" | "viewed" | "replied", "timestamps": {...} }`

No OAuth. No SDK. Just HTTP.

## Sender Verification

First-time senders must verify their email before messages reach the inbox. This prevents spam with spoofed email addresses.

### Unverified sender response (HTTP 202)
{
  "success": true,
  "pending_verification": true,
  "message": "Check your email to deliver your message"
}

### Verification bypass
Senders skip verification if any of these are true:
- Previously verified (cross-tenant — once verified, always verified)
- Whitelisted by the inbox owner
- Trusted reputation score (>= 70)

### Verification endpoint
GET /api/auth/verify-sender?token=<token>
Sent via email to the sender. Verifies email, delivers all pending messages, triggers notifications.

---

## Multi-Tenant Architecture

### URL structure
- Profile page:   https://hmuapi.com/<username>
- API base:       https://hmuapi.com/api/u/<username>

### Legacy routes (jamestannahill only)
The bare /api/pitch, /api/meet, /api/ask, /api/intro, /api/hire, /api/collab, /api/advise, /api/press
routes all issue 301 redirects to /api/u/jamestannahill/<endpoint>.
New integrations should use the /api/u/<username>/<endpoint> form directly.

---

## GET /api/u/<username>
Returns the user's public profile: display name, bio, active channels, and contact preferences.

Response shape:
```json
{
  "username": "jamestannahill",
  "display_name": "James Tannahill",
  "bio": "...",
  "endpoints": ["pitch", "meet", "ask", "intro", "hire", "collab", "advise", "press"],
  "preferences": { ... }
}
```

---

## GET /api/u/<username>/endpoints
Returns the full list of active channels for this user, including field schemas and whether each is enabled.

---

## GET /api/u/<username>/status
Returns the user's current availability, active projects, and estimated response time.

---

## POST /api/u/<username>/<endpoint>
Message submission. Routes to the correct user's inbox, applies their priority scoring rules, and fires their configured notifications.

Replace <username> with any valid username. Replace <endpoint> with one of: pitch, meet, ask, intro, hire, collab, advise, press.

See per-endpoint field schemas below.

---

## POST /api/u/<username>/score — Counter-API: Live Pitch Scoring
Score a message payload before submitting it. Returns a live priority score, breakdown, and recommendation.

Required fields:
- endpoint_slug (string): The channel you intend to submit to (e.g. "pitch", "ask")
- payload (object): The full payload you plan to submit
- session_id (string): A client-generated UUID to correlate scoring sessions

Response:
```json
{
  "score": 85,
  "breakdown": {
    "base": 10,
    "sector_match": 15,
    "urgency": 20,
    "endpoint_condition": 30,
    "reputation": 10
  },
  "recommendation": "Strong — submit now.",
  "session_id": "..."
}
```

Use this endpoint to coach users on how to improve their message priority before sending.

---

## GET /api/status/<token>
Track the delivery status of a submitted message using the token returned at submission time.

Response:
```json
{
  "token": "uuid",
  "status": "received",
  "received_at": "2026-03-12T10:00:00Z",
  "viewed_at": null,
  "replied_at": null
}
```

Status values: "received" | "viewed" | "replied"

---

## POST /api/u/<username>/pitch
Send a deal, partnership, or investment pitch.
Notification: high-priority email.

Required fields:
- name (string, 1-100 chars)
- email (string, valid email)
- type (enum): "investment" | "partnership" | "acquisition" | "other"
- sector (string, 1-100 chars)
- one_liner (string, 10-500 chars): One-line pitch summary

Optional fields:
- deal_size (string): Deal size in dollars
- deck_url (string, URL): Link to pitch deck
- urgency (enum): "low" | "normal" | "high" (default: "normal")

High-priority trigger: deal_size >= $5M or urgency = "high"

---

## POST /api/u/<username>/meet
Request a meeting.
Notification: high-priority email.

Required fields:
- name (string, 1-100 chars)
- email (string, valid email)
- purpose (string, 10-500 chars)

Optional fields:
- duration (enum): "15" | "30" | "60" minutes (default: "30")
- preferred_date (string): Preferred date
- urgency (enum): "low" | "normal" | "high" | "today" (default: "normal")

High-priority trigger: urgency = "today"

---

## POST /api/u/<username>/ask
Ask a question.

Required fields:
- name (string, 1-100 chars)
- email (string, valid email)
- question (string, 10-2000 chars)

Optional fields:
- context (string, max 1000 chars)

---

## POST /api/u/<username>/intro
Request an introduction to someone in the user's network.

Required fields:
- name (string, 1-100 chars)
- email (string, valid email)
- target_person (string, 1-100 chars): Who you want to meet
- reason (string, 10-1000 chars): Why you want the introduction
- relationship_to_you (string, 1-500 chars): How you know this person

---

## POST /api/u/<username>/hire
Send a job opportunity.

Required fields:
- name (string, 1-100 chars)
- email (string, valid email)
- company (string, 1-200 chars)
- role (string, 1-200 chars)
- description (string, 20-5000 chars)

Optional fields:
- compensation (string): Compensation range

---

## POST /api/u/<username>/collab
Propose a collaboration.

Required fields:
- name (string, 1-100 chars)
- email (string, valid email)
- project (string, 1-200 chars)
- description (string, 20-5000 chars)

Optional fields:
- timeline (string, max 200 chars)

---

## POST /api/u/<username>/advise
Request advisory, board, or consulting engagement.
Notification: high-priority email.

Required fields:
- name (string, 1-100 chars)
- email (string, valid email)
- type (enum): "advisory" | "board" | "consulting" | "fractional"
- company (string, 1-200 chars)
- area (string, 10-1000 chars): What you need help with

Optional fields:
- compensation (string): Compensation details
- duration (string, max 200 chars): Expected engagement duration

High-priority trigger: type = "board" or type = "fractional"

---

## POST /api/u/<username>/press
Media, podcast, or speaking invitation.

Required fields:
- name (string, 1-100 chars)
- email (string, valid email)
- outlet (string, 1-200 chars): Publication or outlet name
- type (enum): "interview" | "podcast" | "panel" | "keynote" | "article" | "other"
- topic (string, 10-1000 chars)

Optional fields:
- date (string): Event or publish date
- audience_size (string): Estimated audience size

---

## Legacy GET endpoints (jamestannahill only)

GET /api/status — Equivalent to GET /api/u/jamestannahill/status
GET /api/preferences — Communication guidelines (weekdays 9am-5pm ET, open/closed topics)
GET /api/office-hours — Calendar availability and booking instructions

## GET /api
Returns full API documentation including all endpoints, methods, descriptions, rate limits, and field schemas as JSON.

---

## Terminal usage
```
# Submit to any user
curl -X POST https://hmuapi.com/api/u/jamestannahill/ask \
  -H "Content-Type: application/json" \
  -d '{"name":"Your Name","email":"you@example.com","question":"What are you working on?"}'

# Score a payload before submitting
curl -X POST https://hmuapi.com/api/u/jamestannahill/score \
  -H "Content-Type: application/json" \
  -d '{"endpoint_slug":"pitch","session_id":"abc-123","payload":{"name":"Your Name","email":"you@example.com","type":"partnership","sector":"healthcare","one_liner":"AI triage for ERs"}}'

# Check message status
curl https://hmuapi.com/api/status/<token>
```

---

## Error responses
- 400: Validation failed — includes field-level errors
- 403: Sender is blocked
- 404: Unknown username or endpoint
- 429: Rate limit exceeded — includes retry_after_seconds

## Priority scoring system
Messages are auto-scored on a point system:
- Whitelisted sender: +50
- Returning sender: +10
- High reputation (>=5 messages): +20
- Endpoint high-priority condition met: +30
- Sector match (healthcare, SaaS, AI, ML, LLM, biotech, pharma, medical): +15
- Urgency high/today: +20
- Urgency low: -10

Use POST /api/u/<username>/score to preview the score for any payload before submitting.

---

## About James Tannahill (platform creator)
- Founder & Managing Partner, Plocamium Holdings (private equity)
- Founder, 1nessAgency (healthcare digital marketing)
- Founder, HLTHvrs (HIPAA-compliant AI SaaS for mental health providers)
- Interests: Healthcare, SaaS, private equity, AI/ML, web development
- Location: New York area, ET timezone
- Website: https://jamestannahill.com
- Profile: https://hmuapi.com/jamestannahill