Filoo API

60-second quick start

# 1. Sign up at filoo.app, claim a username, subscribe to Pro or Agents
export FILOO_KEY="flo_live_..."

# 2. Create your first link
curl -X POST https://filoo.app/api/v1/links \
  -H "Authorization: Bearer $FILOO_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "https://example.com/long-url",
    "slug": "campaign-2025"
  }'

# Response:
# {
#   "code": "yourname:campaign-2025",
#   "short_url": "https://filoo.app/yourname/campaign-2025",
#   "destination": "https://example.com/long-url",
#   "created_at": 1736789012,
#   "active": true
# }

# 3. Read the stats anytime
curl https://filoo.app/api/v1/links/yourname:campaign-2025/stats \
  -H "Authorization: Bearer $FILOO_KEY"

That's it. Your link is live. Every scan is tracked.

Authentication

All API requests require a Bearer token in the Authorization header. Tokens are prefixed `flo_live_` and shown only once at creation time.

Generate keys at filoo.app/dashboard/api-keys.

Authorization: Bearer flo_live_xxxxxxxxxxxxxxxx

Each Pro account can issue up to 5 keys. Agents up to 50. Revoke any key at any time. The previous one stops working immediately.

Keys are HMAC-hashed in our database. We literally cannot recover yours if you lose it. Generate a new one and rotate.

Outbound webhooks

Filoo sends a signed POST to your endpoint when events you subscribe to happen. Configure at filoo.app/dashboard/webhooks.

Subscribed event types:

Payload example:

{
  "id": "evt_01H8K...",
  "type": "link.scanned",
  "created_at": 1736789012,
  "data": {
    "link_code": "jr:q4-launch",
    "country": "FR",
    "device_type": "mobile",
    "referrer_host": "twitter.com"
  }
}

Each request includes an `X-Filoo-Signature` header containing `sha256=<hex>`. The signature is HMAC-SHA256 of the raw request body, using the webhook secret you configured.

# Use the TypeScript or Python tab — language-specific signature verification.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(body: string, signature: string, secret: string): boolean {
  const expected = 'sha256=' + createHmac('sha256', secret).update(body).digest('hex');
  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

import hmac, hashlib

def verify(body: bytes, signature: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Replays: each event has a unique `id`. Your handler should be idempotent. We retry up to 5 times with exponential backoff if your endpoint returns non-2xx.

Rate limits

Per API key, sliding window: Pro: 100 requests / minute Agents: 1,000 requests / minute When exceeded, you get HTTP 429 with a `Retry-After` header in seconds.

HTTP/2 429
Retry-After: 18
Content-Type: application/json

{"error":"rate_limited","retry_after":18}

Daily creation limits are separate (200/day Pro, 5,000/day Agents). Exceeding those returns 429 with `error: "daily_limit"`. Active link limits are checked at creation, returning 429 with `error: "active_limit"` when full. Buy a Boost Pack or upgrade.

AI agent integration

Filoo is built for AI agents. Give your agent a single API key and let it create, track, and modify short links programmatically — no dashboard required.

How it works

Your agent gets one or more short links it can reuse across sessions. Each link is observable: the agent can read click totals, top countries, and referrer data at any time via the stats endpoint. And each link is editable: the agent can rotate the destination URL without changing the short link — perfect for A/B testing, campaign updates, or correcting a mistake after the link is live.

Example workflow

1. 1. Agent calls POST /api/v1/links with a destination URL and a descriptive slug → receives { code, short_url }
2. 2. Agent embeds the short_url in an email, Slack message, or generated document
3. 3. When someone clicks the link, Filoo logs the scan with country, device, referrer, and timestamp
4. 4. Agent calls GET /api/v1/links/{code}/stats → receives totals, top_countries, top_sources
5. 5. Based on stats, agent calls PATCH /api/v1/links/{code} with a new destination URL → destination rotates, link unchanged
6. 6. Loop: the agent reads stats, decides, and adapts — all via the same API.

Prompts for AI coding tools

Use these prompts with Cursor, Claude Code, Copilot, or any AI coding tool to integrate Filoo instantly:

Best practices for agent-managed links

• Use labels — set the label field on each link so your agent can identify links by purpose when listing them later.
• Rotate destinations for A/B testing — keep the short URL constant, change the destination via PATCH, and compare stats before vs. after.
• Monitor click analytics — have your agent poll stats periodically or subscribe to link.scanned webhooks for real-time feedback.
• Set descriptive slugs — use human-readable slugs like campaign-q2-v1 so debugging via the dashboard stays easy.
• Clean up inactive links — use DELETE /api/v1/links/{code} to retire links that have stopped receiving traffic, staying under your active link cap.
• Use the Agents tier — 50,000 active links, 5,000 creations/day, 1,000 API req/min. Designed specifically for autonomous workloads.

Most useful endpoints for agents

The existing Filoo API already covers everything an agent needs. The most relevant endpoints are:

• POST /api/v1/links — Create a new short link (agents can generate hundreds automatically)
• GET /api/v1/links/{code}/stats — Read scan totals, countries, and referrers
• PATCH /api/v1/links/{code} — Update the destination URL (rotate without breaking the short link)
• GET /api/v1/links — List all links with cursor pagination (find links by label or date)
• GET /api/v1/usage — Check daily creation quotas and active link counts before generating more

Error format

All error responses follow this shape:

{
  "error": "machine_readable_code",
  "message": "Human-readable explanation",
  "details": {}
}

Codes by HTTP status:

  400 invalid_input | 401 not_authenticated | 403 forbidden
  404 not_found     | 409 conflict          | 422 unprocessable
  429 rate_limited  | 500 server_error      | 503 service_unavailable

Specific 422 codes: malicious_destination, blocked_destination,
slug_reserved, username_inactive.
Specific 429 codes: rate_limited, active_limit, daily_limit.

Specification

The full schema is published as OpenAPI 3.0 at https://filoo.app/api/openapi.json Import into Postman, Insomnia, Swagger UI, or generate clients in any language with openapi-generator.

Changelog

Stable since v0.3.1 (2026-05-10). No breaking changes planned. Track at filoo.app/changelog.