Authentication

Every endpoint authenticates via one of two headers. Both keys are pre-loaded for this environment — copy from the chips below. Get a personal API key from the dashboard after signing up; it replaces the public guest key and unlocks your tier's per-day quotas.

Tiers

API keys (this environment)

The public site token below is safe to use in the browser. Write endpoints (including POST /api/blog/post) require the single admin master key, which is never exposed on this public page — copy it from the admin console.

Code examples — every tool, every language

Every tool runs through the same flow: POST /api/tool-run returns a job_id, you poll /status, then read /results. Pick a tool and a language below — each sample is a complete, runnable client (start → poll → results). Replace YOUR_API_KEY with your personal key from the dashboard (a free Registered account works — tool runs require a signed-in key, not the public guest token).

Loading…

Languages: cURL · Python · Node.js · Java · Kotlin · Swift · Flutter/Dart. Swap the tool and params for any other tool key listed under POST /api/tool-run.

Errors

All errors follow this shape:

{"detail": "Human-readable error"}

Rate limits

Per-IP rate limit is 60 req / min. Pro plans get 600 req / min. Excess returns 429 with a Retry-After header.

POST /api/auth/signup

Creates a new registered user. The first 100 signups are flagged pro_eligible=true — they can claim a 30-day Pro trial via /api/auth/claim-pro.

curl -X POST https://convertfleet.online/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email":    "you@example.com",
    "password": "your-strong-password",
    "name":     "Aisha"
  }'

Response

{
  "status": "success",
  "user": {
    "id": "uuid", "email": "...", "api_key": "sk-...",
    "tier": "registered", "pro_eligible": true, "pro_expires_at": null
  }
}

POST /api/auth/login

Verify password and return the user's api_key. Store it client-side and send as x-api-key on every subsequent request.

curl -X POST https://convertfleet.online/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-strong-password"}'

GET /api/auth/me

Returns the profile + usage counters for the api_key holder.

curl https://convertfleet.online/api/auth/me \
  -H "x-api-key: pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw"

POST /api/auth/update

Update name and/or password. Password change requires current_password.

curl -X POST https://convertfleet.online/api/auth/update \
  -H "x-api-key: YOUR_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Aisha P.",
    "current_password": "old-pw",
    "new_password":     "new-strong-pw"
  }'

POST /api/auth/regenerate-key

Rotate the personal API key. The old key is invalidated immediately.

curl -X POST https://convertfleet.online/api/auth/regenerate-key \
  -H "x-api-key: YOUR_USER_KEY"

POST /api/auth/claim-pro

One-shot — activates a 30-day Pro window for an eligible account.

curl -X POST https://convertfleet.online/api/auth/claim-pro \
  -H "x-api-key: YOUR_USER_KEY"

POST /api/blog/post

Publish a blog post from an external system. Authenticates with the admin master key (header x-api-key). Posts created here are tagged source=api.

Required fields

• title — string
• content — string (HTML or plain text)

Optional fields

• slug — URL slug, auto-derived from title if omitted
• excerpt — short card-preview summary
• category — defaults to Lead Generation
• status — "draft" or "published"
• is_featured — boolean, pins the post on the blog homepage
• meta_description — SEO meta description
• seo_keywords — comma-separated string or keywords as an array
• featured_image — URL of the hero image (alias of image_url)

curl -X POST https://convertfleet.online/api/blog/post \
  -H "x-api-key: YOUR_ADMIN_MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My Post",
    "slug": "my-post",
    "content": "<p>HTML or text</p>",
    "excerpt": "Short summary",
    "category": "Technology",
    "status": "draft",
    "is_featured": false,
    "meta_description": "SEO description",
    "seo_keywords": "key1, key2, key3",
    "featured_image": "https://example.com/cover.jpg"
  }'

POST /api/blog/generate

Generate and publish in one call. Uses any valid user API key (paid tiers recommended — image generation is slow). Returns the full article payload plus the inserted post id.

curl -X POST https://convertfleet.online/api/blog/generate \
  -H "x-api-key: YOUR_USER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"topic":"apollo vs clay email verification 2026"}'

GET /api/blog/list

Public read of all blog posts, newest first.

curl https://convertfleet.online/api/blog/list

POST /api/tool-run

Kick off any tool. Returns a job_id immediately — poll status or open the WebSocket.

Tool keys

mapsrev linkedin fb fbads reddit tiktok twitter yt yt_comp dl dl_yt dl_ig dl_tt dl_fb dl_sn email disposable webemail websearch

curl -X POST https://convertfleet.online/api/tool-run \
  -H "x-api-key: pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "mapsrev",
    "params": {
      "place_url": "https://maps.google.com/...",
      "max_results": 200
    }
  }'

GET /api/tool-run/{job_id}/status

curl https://convertfleet.online/api/tool-run/JOB_ID/status \
  -H "x-api-key: pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw"

GET /api/tool-run/{job_id}/results

curl https://convertfleet.online/api/tool-run/JOB_ID/results \
  -H "x-api-key: pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw"

POST /api/search

Search the web and scrape every result page in one synchronous call. Returns the ranked links and, for each one, the page itself: title, meta description, canonical, language, H1/H2 headings, readable body text, word count, emails, phones, social profiles, Open Graph / Twitter cards and JSON-LD structured data. Built for agents that need an answer in one round trip — use POST /api/tool-run with {"tool":"websearch"} for long, pollable runs with CSV / XLSX export.

Body fields

• query — string, the search query (or queries, an array, to run several)
• urls — array, scrape these pages directly and skip the search step
• max_results — int, links per run. Clamped to your plan and shared across multiple queries (they don't multiply it). Send 0 for "as many as my plan allows".
• scrape_pages — boolean, default true. false = links + snippets only (fast).
• site — string, restrict to one domain (enforced server-side)
• time_range — day · week · month · year
• engine — auto (default, Google first then a labelled fallback), google (Google only — errors if unavailable), or a named engine
• allow_fallback — boolean, default true. false = fail rather than answer from a non-Google engine.
• text_chars — int, body text returned per page (default 5000)
• include_contacts / include_structured — boolean, default true
• include_links / include_images — boolean, default false

Per-plan budget

One run is N result links and N full page fetches, so the plan bounds the whole crawl — not just a list length. Every value below is clamped server-side, for REST and MCP callers alike, and the budget that was applied comes back in the response as plan_limits. GET /api/search/status reports yours.

• Starter — 10 results · 10 pages · 2 queries · 5,000 chars/page · 4 parallel fetches · 10 min
• Pro — 50 results · 50 pages · 10 queries · 50,000 chars/page · 8 parallel fetches · 20 min · browser engine
• Gold — 200 results · 200 pages · 25 queries · full-page text (200,000 chars) · 12 parallel fetches · 30 min · browser engine

Over-large requests are clamped, never rejected. The synchronous endpoint caps its own wall-clock at 5 minutes whatever the plan allows — use POST /api/tool-run for runs longer than that.

curl -X POST https://convertfleet.online/api/search \
  -H "x-api-key: pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "best crm software for real estate",
    "max_results": 5,
    "scrape_pages": true,
    "text_chars": 5000
  }'

Response

{
  "engine_used": "bing",
  "google_used": false,
  "notice": "Google did not serve this server …results come from bing and are labelled as such.",
  "links_found": 5,
  "pages_scraped": 4,
  "results": [
    {"rank": 1, "title": "11 Best CRM Software in 2026", "url": "https://www.g2.com/articles/best-crm-software",
     "domain": "g2.com", "snippet": "I evaluated 30+ tools…", "engine": "bing",
     "status": "ok", "words": 8374, "emails": "", "h1": "Best CRM software", "text": "…"},
    {"rank": 2, "title": "The best CRM software to try", "url": "https://www.producthunt.com/categories/crm",
     "domain": "producthunt.com", "status": "HTTP 403", "words": 0}
  ],
  "pages": [ /* full nested page objects: headings, structured_data, socials… */ ],
  "count": 5,
  "warnings": ["1 page(s) could not be scraped: producthunt.com: HTTP 403"]
}

Honest results. Every row carries the engine that produced it and the payload sets google_used — a fallback engine is never presented as a Google ranking. A page that blocks the scraper returns that reason in its status while the rest of the run continues, and if no engine answers at all the call returns 502 with the reason rather than an empty success.

GET /api/search/status

Which Google providers are configured and whether google.com is currently answering — call it before a search if your agent needs to know it will get a real Google ranking.

curl https://convertfleet.online/api/search/status \
  -H "x-api-key: pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw"

{
  "providers": {"serper": false, "serpapi": false, "google_cse": false},
  "proxy_configured": false,
  "google_ready": false,
  "google_cooldown_active": true,
  "last_google_block_reason": "Google served the JavaScript-required interstitial (no results markup) to this IP",
  "engines": ["auto", "google", "bing", "duckduckgo", "brave", "mojeek", "yahoo", "…"],
  "note": "Real google.com rankings need SERPER_API_KEY, SERPAPI_KEY or GOOGLE_CSE_KEY + GOOGLE_CSE_CX (or a residential SEARCH_PROXY)…"
}

POST /api/website-email/find

Crawl a single website (same-site pages only) and return every email it finds, plus phones and social links. Prioritises contact / about / team pages, de-obfuscates "name [at] domain [dot] com", and tags each address personal or role.

Body fields

• website — string, the site to crawl (a bare host like acme.com is fine)
• max_pages — int, crawl budget. Clamped to your plan's per-run ceiling.
• include_phones — boolean, default true
• include_socials — boolean, default true

curl -X POST https://convertfleet.online/api/website-email/find \
  -H "x-api-key: pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw" \
  -H "Content-Type: application/json" \
  -d '{
    "website": "https://acme.com",
    "max_pages": 12,
    "include_phones": true,
    "include_socials": true
  }'

Response

{
  "website": "https://acme.com",
  "domain": "acme.com",
  "pages_scanned": 9,
  "emails": ["jane.doe@acme.com", "sales@acme.com"],
  "phones": ["+1 555-0100"],
  "socials": [{"platform": "linkedin", "url": "https://linkedin.com/company/acme", "host": "linkedin.com"}],
  "results": [
    {"email": "jane.doe@acme.com", "type": "personal", "domain": "acme.com", "source_page": "https://acme.com/team"},
    {"email": "sales@acme.com",    "type": "role",     "domain": "acme.com", "source_page": "https://acme.com/contact"}
  ],
  "count": 2
}

Also available via POST /api/tool-run with {"tool":"webemail","params":{...}} for tracked, pollable jobs with CSV / XLSX export.

AI agents — MCP server

Everything documented on this page is also callable by AI agents over the Model Context Protocol. Point Hermes, Claude, Cursor, OpenClaw, n8n, Zapier or Make at one endpoint and they get every ConvertFleet tool, with the same plan limits and the same monthly quota.

https://convertfleet.online/mcp
Authorization: Bearer <cfm- scoped token or sk- API key>

The server tells the agent how to use itself: it returns usage instructions on connect, every tool description says when to use it and what it is not for, and the find_tool helper turns a plain-English job into the right tool with example arguments.

• MCP documentation — endpoint, authentication, job handling, error codes.
• Quickstart — copy-paste setup for ten clients.
• Tool reference — every tool with parameters, result fields and both the MCP and REST call.
• Recipes — multi-tool workflows (lead lists, ad audits, web research, list hygiene).
• docs.md · manifest.json · llms.txt — machine-readable, no auth.

Mint a scoped MCP token — restricted to the exact tools one agent may call, revocable on its own — in your dashboard → MCP / Agents.

GET /api/health

Liveness probe. Always 200.

curl https://convertfleet.online/api/health

GET /api/download/{job_id}/{fmt}

Direct file download for a finished job. fmt = csv or xlsx.

curl -L -o leads.csv \
  -H "x-api-key: pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw" \
  https://convertfleet.online/api/download/JOB_ID/csv