# Rentiful Conversations

Storage and retrieval API for renter conversation threads (email + WhatsApp).
Stores structured messages, dedupes by content hash, exposes a prioritised
follow-up queue, and tracks per-renter opportunities. The service does not
parse content or send messages — callers submit already-structured data.

This URL is the agent-facing entry point.

## Start here

- **Agent manual** → /llms.txt (public — quick orientation, copy-paste examples)
- **Full agent guide** → /v1/conv/agents.md (public — deep operating guide)
- **OpenAPI spec** → /openapi.yaml (public, YAML) | /swagger (public, interactive UI)
- **Health** → /health (public, JSON)

## Authentication

Discovery endpoints above are public. Every other `/v1/conv/*` endpoint
requires:

```
Authorization: Bearer <CONVERSATIONS_API_SECRET>
```

The secret is shared by the operator out-of-band.

## Common calls (auth required)

| Goal | Endpoint |
|---|---|
| Bulk import a parsed thread | `POST /v1/conv/import` |
| Prioritised work queue | `GET /v1/conv/renters/needs-action` |
| Look up a renter | `GET /v1/conv/renters/{renter_key}` |
| Update a renter | `PATCH /v1/conv/renters/{renter_key}` |
| Merge two renters | `POST /v1/conv/renters/{source}/merge-into/{target}` |
| Add an opportunity | `POST /v1/conv/renters/{renter_key}/opportunities` |