Tagrly agent guide.

What Tagrly is#

A workspace-scoped image catalog. A customer connects a Google Drive or Dropbox folder; every image is analyzed by Claude vision against a structured schema and stored with the resulting fields: focal subject, scene, lighting, time of day, mood, quality, a marketing-graphic flag, what is visible, and whatever else the detected vertical adds.

The API is the agent-facing surface on that catalog. You describe a page; it returns images from that customer's library. It never pads a result to hit a count: when the library is thin on a subject the response carries a gap_signal naming the shots that are missing.

Calling it without a key#

No key required POST /api/try/analyze-photo is the one endpoint that takes no authentication at all. Send a single image as multipart/form-data under the field name photo. It runs the same prompt and JSON schema a paying workspace gets, returns the reading, and persists nothing. No session, no disk write, no database row.

curl -X POST https://tagrly.com/api/try/analyze-photo \
  -F "photo=@kitchen.jpg"

Authentication#

Every other endpoint takes one header:

Authorization: Bearer tagrly_pk_<workspace-slug>_<32 hex chars>

Keys are workspace-scoped: one key reaches exactly one tenant's catalog. Only the SHA-256 hash is stored, so the visible key is shown once and cannot be recovered. A lost key is replaced, not read back. Revoking a key stops it resolving on the very next request.

MCP server#

Everything below is also served over the Model Context Protocol at https://tagrly.com/mcp (Streamable HTTP, stateless, spec revision 2025-06-18). Authenticate with the same Authorization: Bearer tagrly_pk_... header; initialize and tools/list work without a key, every tools/call requires one.

Six tools map onto the endpoints in this guide: search_photos (GET /api/search, with compact records), find_photos (POST /api/find), get_page_images (POST /api/page), get_image (GET /api/image/{id}), log_usage (POST /api/usage) and list_collections (GET /api/collections). Each tool call is dispatched through the corresponding HTTP endpoint internally, so the behavior, scoping, metering and error semantics in this guide apply verbatim on both surfaces. The two model-curated tools spend one metered ask each, exactly like their endpoints.

The core loop#

For most work the loop is five steps, four of them one call each.

1. Decide which section of the page you are filling (hero, gallery, room, detail).
2. Call POST /api/page with a plain-English topic for that section.
3. Render each pick's hosted_url with the alt_rewrite Tagrly wrote for it.
4. Post the rendered drive_ids to /api/usage.
5. Pass exclude_recently_used_days on the next call, so a long automation never repeats an image.

Endpoints#

POST /api/page#

The smallest useful request is one field.

POST /api/page
Authorization: Bearer tagrly_pk_acme_…
Content-Type: application/json

{ "topic": "weekend brunch on our rooftop patio" }

Request fields#

Response#

{
  "ok": true,
  "topic": "weekend brunch on our rooftop patio",
  "layout": "food-drink",
  "slots": {
    "hero":         { "wanted": 1, "got": 1, "picks": [ … ] },
    "product_grid": { "wanted": 6, "got": 6, "picks": [ … ] },
    "experience":   { "wanted": 3, "got": 3, "picks": [ … ] }
  },
  "gap_signal":  { "fired": false, … },
  "diagnostics": { "claude_cost_usd": 0.029, "elapsed_ms": 9021, … }
}

Each slot also reports candidates_considered, shortlisted and an on_topic_score_distribution, which together tell you whether a thin result means a thin library or a narrow topic.

Fields on every pick#

Layout detection#

First match wins, and matching happens within the workspace's vertical, a food topic only reaches the food layout in a hospitality workspace.

POST /api/brief#

Same pipeline, your slots. Reach for it when the auto layout does not match your template (a multi-section homepage, an unusual grid, a template that needs exactly eight images in one band). Every field from /api/page applies, plus three.

POST /api/brief
{
  "topic": "our outdoor patio brunch",
  "h1":    "Weekend Brunch on the Patio",
  "slots": [
    { "role": "hero", "count": 1,
      "must_have": ["focal:food-or-drink"],
      "prefer":    ["quality>=75", "negative_space"],
      "diversity": "none",
      "description": "Lead photo, drink and dish together if possible." },
    { "role": "gallery", "count": 8,
      "must_have": ["focal:food-or-drink|focal:product-or-object"],
      "prefer":    ["quality>=70"],
      "diversity": "subject+angle",
      "description": "Eight distinct dishes. Vary the angles." },
    { "role": "atmosphere", "count": 4,
      "must_have": ["people>=2"],
      "prefer":    ["mood:lively|mood:celebratory"],
      "diversity": "subject+angle",
      "description": "Group moments on the patio." }
  ]
}

The slot language#

Two lists per slot. must_have is a hard filter and every item must pass. prefer is soft scoring: matches earn a bonus, misses are not excluded. Within one string, alternatives join with |.

Usage ledger#

This is what stops a fifty-post automation from using the same hero fifty times. Log what you rendered, then exclude by age on the next call.

POST /api/usage
{
  "items": [
    { "drive_id": "1xabcd…",
      "page_url": "https://customer.com/brunch",
      "page_topic": "weekend brunch",
      "slot_role": "hero" }
  ]
}

drive_ids comes back de-duplicated and sorted, which is exactly the shape exclude_image_ids expects, so a recent-use exclusion is one call and no reshaping.

GET /api/search#

The primitive under everything else: keyword and facet search with no model in the loop, so it is free and fast. Returns { count, results } where each result carries the catalog fields, but not alt_rewrite, on_topic_score or why_picked, because nothing curated it.

The remaining endpoints#

Applied defaults#

These run on every curated call whether you ask or not. Knowing them explains most surprising results.

The gap signal#

When the curator cannot fill a slot honestly, it returns fewer images and explains itself rather than padding the count.

"gap_signal": {
  "fired": true,
  "shortfall_total": 3,
  "slots_short": [ { "role": "action_grid", "short_by": 3 } ],
  "explanations": [
    "[action_grid] Only 3 candidates show team gear as the focal
     subject; the rest had it only in branded items."
  ],
  "would_help": [
    "Close-up of 3-4 fans in team jerseys at the bar counter",
    "Wide shot of a fan crowd raising drinks together"
  ],
  "recommendations": [ { "type": "retag_pass", … } ]
}

Workspaces and verticals#

Every call is scoped to the workspace its key unlocks. A workspace declares a vertical, which decides both the analyzer overlay applied to its photographs and the layout family /api/page can reach.

A workspace can also carry a free-text overlay appended to the analyzer prompt for that tenant only, and a manual synonyms table for slang the catalog would never see on its own. Both are configured by the customer. Your agent does not need to touch either. /api/page already knows the customer's domain.

Limits, ceilings and cost#

Cost is reported, not estimated: every curated response carries diagnostics.claude_cost_usd for that exact call, alongside the token counts and the model used. Budget from that number rather than from a table on a marketing page. Uncurated calls, /api/search, the usage endpoints, everything under the remaining endpoints, run no model and cost nothing.

The spend cap is a circuit breaker rather than a quota. Before curating, the pipeline estimates the cost of the slots in the request; if that estimate exceeds cost_cap_usd, curation is skipped and the slots fall back to deterministic ranking. The response says so in diagnostics.cost_cap_hit, so a call never fails silently or bills past its ceiling.

Errors and retries#

One more shape worth knowing: an anonymous request to a keyed endpoint does not always return 401. Signed-out browser traffic is redirected to sign-in before the endpoint runs, so a client that follows redirects can receive an HTML page with a 200. Send the Authorization header on every keyed call and the question never arises.