Build with Arlo.

Quick start

One curl. No SDK required.

curl https://api.arlotv.ai/v1/recommendations \
  -H "X-API-Key: arlo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quiet documentary, sunday morning",
    "limit": 3
  }'

query is required; limit defaults to 5, max 20. The response is JSON with a results array of ranked, scored picks from your catalog:

{
  "results": [
    {
      "content_id": "first-reformed",
      "title": "First Reformed",
      "description": "Schrader at his most precise...",
      "pdp_url": "https://...",
      "image": "https://...",
      "final_score": 0.91,
      "components": { "semantic": 0.82, "behavior": 0.12, "diversity": 0.04, "zeitgeist": 0 },
      "vibe": "austere, contemplative",
      "personalized": false,
      "genres": ["Drama"],
      "year": 2017,
      "runtime_minutes": 113,
      "content_rating": "R"
    }
  ],
  "strategy": "semantic",
  "cold_start_tier": null,
  "request_id": "uuid"
}

Authentication

Every request is authenticated with the X-API-Key header — or, equivalently, Authorization: Bearer <key> (both are accepted; X-API-Key is canonical and wins if you send both). Get a key from your dashboard or self-serve at signup.

Two key flavors per organization:

• arlo_live_* — production. Counts toward your tier's usage cap.
• arlo_test_* — development and testing.

API keys are server-side only — never embed a key in browser or app code. Keys are shown once at creation and stored hashed; keep yours in a secrets manager and call Arlo from your backend.

X-API-Key: arlo_live_8a3f...e0b2
# — or —
Authorization: Bearer arlo_live_8a3f...e0b2

Embed rails

Personalized, gray-label "For You" rails for your own UI — the flagship partner endpoint. Your backend sends the user's current taste signals; Arlo uses them as ranking input for that request only, scopes the output to your catalog, and returns rails. Arlo stores no user data — customer_id is an opaque pass-through key, never a stored identity.

{
  "customer_id": "your-opaque-user-id",
  "signals": {
    "favorites": ["content_id", "..."],
    "likes":     ["content_id", "..."],
    "dislikes":  ["content_id", "..."]
  },
  "max": 6,
  "country": "US"
}

• customer_id — required. Opaque; never send PII.
• signals — optional. Omit or send empty arrays for cold-start users; Arlo falls back to catalog-scoped editorial/popular rails.
• max — optional, caps rail count. country — optional, default US.

Response:

{
  "rails": [
    {
      "rail_id": "string",
      "title": "Because you liked ...",
      "items": [
        { "content_id": "string", "rec_id": "string", "position": 0 }
      ]
    }
  ]
}

• content_idis your catalog's content identifier — resolve it against your own CMS for artwork, metadata, and play URLs.
• rec_idis Arlo's recommendation-attribution id. Echo it on the click and deeplink events you send back so recommendations are attributable end to end.
• Fail-silent contract: this endpoint never breaks your page. Any internal failure returns 200 {"rails": []} — always render your own baseline when rails is empty.

Recommendations

Natural-language query in, ranked and scored picks from your catalog out — for search boxes, "surprise me" buttons, and editorial tooling. Pass an optional X-User-Token header (an end-user token) to enable personalized reranking.

{
  "query": "quiet documentary, sunday morning",
  "limit": 5,
  "exclude": ["already-shown-slug"],
  "context": { "country_code": "US", "platform": "api" }
}

• query — required.
• limit — optional, default 5, max 20 (capped server-side).
• exclude / context — optional.

Response is the shape shown in the quick start: a top-level results array plus strategy, cold_start_tier, and request_id.

Title enrichment

Full record for a single title: raw catalog metadata plus Arlo's text + visual enrichment (summary, themes, audience context, tone score, color palette, shot style).

Query string: ?client_id=<catalog>. client_id required. Unknown slugs return 404.

Orgs & keys

Self-serve organization and key lifecycle. Signup is public; everything else is authenticated with your X-API-Key.

MCP

For AI agents (Claude, ChatGPT, Cursor, n8n, anything MCP-aware), use the Model Context Protocol endpoint instead of REST — Streamable HTTP transport, same X-API-Key auth. A key is required on every request — there is no anonymous tier.

Full tool surface, connection guides per host (Claude Desktop / Cursor / n8n), and tiered rate limits documented in the MCP guide.

Errors

Standard HTTP codes. Body is always JSON with an error message.

Rate limits

Per-tier monthly quotas + per-minute burst caps. Quota resets at the start of each billing cycle. 429 responses include a Retry-After header, and every response carries X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset headers.

SDKs

The REST API is plain JSON over HTTPS — every language has it. First-party SDKs:

• TypeScript — @arlotv/mcp — available on request; npm publish imminent
• Python — coming soon

Until then, curl + your HTTP library of choice works fine. Sample integration: see the chat app at app.arlotv.ai.