---
name: hemlo-api
description: Call the Hemlo REST API (/api/v1) for broker work — deals, meetings and capture, tasks, documents, Trygghetskoll checks, listing drafts, discrepancies, style profiles with sold-listing links, and approvals. Use for scripts, integrations or agents without MCP support, or when you need exact request/response shapes.
license: Proprietary
metadata:
  author: hemlo
  version: "1.0"
---

# Hemlo REST API

- Base URL (staging): `https://api.staging.hemlo.ai/api/v1`
- Reference: `https://api.staging.hemlo.ai` (endpoint list), contract in OpenAPI 3.1
- Auth: `Authorization: Bearer hsk_u_…` (see **hemlo-keys**)
- Tag agent traffic: `x-hemlo-channel: mcp` (shows up in the audit log and AI usage ledger)
- JSON in and out, snake_case. Errors: `{ "error": { "code": "...", "message": "..." } }`

## Smoke test

```bash
curl -s https://api.staging.hemlo.ai/api/v1/me \
  -H "Authorization: Bearer $HEMLO_API_KEY" -H "x-hemlo-channel: mcp"
```

## Main endpoints

| Area | Endpoints |
| --- | --- |
| Identity | `GET/PATCH /me` |
| Today | `GET /broker/today` |
| Deals | `GET/POST /deals`, `GET/PATCH/DELETE /deals/{id}`, comparables, tasks, documents, `PATCH /deals/{id}/checks` |
| Meetings | `POST /deals/{id}/meetings`, `GET/PATCH/DELETE /meetings/{id}`, `POST /meetings/{id}/capture`, coaching |
| Tasks | `PATCH/DELETE /tasks/{id}` |
| Listings | `GET/POST /listing-drafts`, `GET/PATCH/DELETE /listing-drafts/{id}`, `POST /listing-drafts/{id}/style`, `POST /listing-drafts/{id}/approve`, discrepancies |
| Stilprofil | `GET/PUT/DELETE /style-profile`, `PUT/DELETE /organizations/{id}/style-profile` |

## Stilprofil from sold properties

Send example texts, links to up to 20 properties the broker has sold, or both:

```bash
curl -s -X PUT https://api.staging.hemlo.ai/api/v1/style-profile \
  -H "Authorization: Bearer $HEMLO_API_KEY" -H "Content-Type: application/json" \
  -d '{"links":["https://www.example-maklare.se/objekt/123","https://www.example-maklare.se/objekt/456"]}'
```

Hemlo fetches each public page, reads the listing description and analyzes it with the texts.
The response lists every link with `status` (`ok`/`failed`), `title` and `error`. Omitting
`samples` or `links` keeps the saved ones; `[]` clears them. `too_many_links` (> 20),
`invalid_link` (not http/https) and `links_unreadable` (no texts and no readable link) are 400s.

## Capture a meeting

```bash
curl -s -X POST https://api.staging.hemlo.ai/api/v1/meetings/$MEETING_ID/capture \
  -H "Authorization: Bearer $HEMLO_API_KEY" -H "Content-Type: application/json" \
  -d '{"mode":"dictation","transcript":"Säljaren berättade att balkongen vetter mot söder…"}'
```

`mode: "recording"` also needs `recording: { duration_seconds, seller_consented: true }` (the seller
was informed, GDPR). Check the exact body against the endpoint reference before writing; required fields differ per
operation and unknown fields are rejected with `bad_request`.