# Tagrly

> Tagrly is an agent-first image catalog. Customers connect a Drive or Dropbox folder; every photo is analyzed by Claude vision with ~30 structured signals; an AI assistant (Claude Code, Cursor, ChatGPT, n8n) calls our API to describe a page and gets back the right images, with alt text already written and an honest gap signal when the library is thin on a topic.

## Primary documentation for AI agents

- [Agent guide](https://tagrly.com/agent-guide.md): complete technical reference. Endpoints, slot DSL, multi-call recipes, gap-signal handling, cost expectations. **Start here for any AI integration.**
- [Developers](https://tagrly.com/developers.md): marketing-grade overview of the API for human evaluators.

## API endpoints (workspace-scoped, Bearer-token auth)

- `POST /api/page` — magic call. Plain-English topic in, page-ready images out. Auto-detects layout family from topic + workspace vertical.
- `POST /api/brief` — explicit slot control. You define count + must_have + prefer; everything else (FTS + auto-discovery + Haiku curation + gap signal) works the same way.
- `POST /api/usage` — log which images you rendered. Pair with `exclude_recently_used_days` on subsequent calls so a 50-post automation never recycles.
- `GET /api/usage/recent` — list recently rendered images for this workspace.
- `GET /api/search` — low-level keyword search. Returns raw matches without LLM curation.
- `GET /api/image/{drive_id}` — full analysis payload for one image.
- `GET /api/collections` — workspace's curated collections.
- `POST /api/add-to-collection` — save a set for human review.

## Authentication

One header on every request:

```
Authorization: Bearer tagrly_pk_<workspace_slug>_<32 hex chars>
```

Keys are workspace-scoped, generated via `/settings → API keys`, hashed at rest (only the hash is stored).

## What Tagrly does on your behalf (defaults)

- **Promo-graphic filter (default on)** — excludes images flagged as marketing posters / text-overlay graphics.
- **Time-of-day filter (auto)** — topics mentioning "brunch", "morning", "lunch" only return daytime images. "Late night", "after hours" only return nighttime.
- **Cross-slot dedup** — no image appears in more than one slot per call. Slot order is priority order.
- **Recent-use dedup (opt-in)** — pass `exclude_recently_used_days: N` to skip images logged via `/api/usage` in the last N days for this workspace.
- **Workspace-scoped vocabulary** — synonyms + entity vocabulary live per-tenant; no cross-tenant bleed.
- **Vertical-specific analyzer** — workspaces declare a vertical (hospitality-sports, wedding-venue, real-estate-listing, etc.). The analyzer prompt adapts accordingly.

## Typical agent loop

1. Decide what section of a page you're filling.
2. `POST /api/page` with a plain-English topic for that section.
3. Render `picks[].hosted_url` + `picks[].alt_rewrite`.
4. `POST /api/usage` with the rendered drive_ids.
5. On the next page, pass `exclude_recently_used_days` so you don't repeat.

## Cost expectations

- `POST /api/page` (3 slots): ~$0.025-0.035 per call
- `POST /api/brief` (6 slots): ~$0.05-0.06 per call
- `GET /api/search` / `POST /api/usage`: $0 (no LLM)

## Gap signal

When the curator can't fill a slot honestly, the response includes a `gap_signal` with concrete `would_help` suggestions that read like a photo-shoot brief. Don't pad — the gap signal exists so your agent can route to AI generation, request a re-tag pass, or surface the missing-shots list to the customer.

## Optional

- [Site marketing](https://tagrly.com/): plain-English overview for non-technical buyers.
- [Pricing](https://tagrly.com/pricing): plans + quotas.
- [About](https://tagrly.com/about): the company behind the product.