Pre-launch beta — Pro plan free for the first 100 signups. 0 claimed 100 left Claim →

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

TierPer runAPI calls / dayRetention
Guest2052h
Registered200506h
Pro1,00050024h

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.

Public site token x-api-key

Use on read endpoints, /api/tool-run, /api/blog/list, etc. Rate-limited, never admin.

pub-SlLO-K41HYVaytaEVYbSzG3F4U2BNepk8oPFnw

Admin master key x-api-key

The single secret key for all write/admin endpoints, including POST /api/blog/post. Not shown here — reveal & 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 below. Using n8n or Make.com? Skip the code entirely — the two buttons under the tool picker download a workflow with all three calls already wired together. Otherwise pick a language: each call gets its own box and its own Copy button, so a Zap, where every call is a separate step, needs no hand-splitting. 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 · Zapier · Java · Kotlin · Swift · Flutter/Dart — plus one-click n8n and Make.com workflow downloads for every tool. Swap the tool and params for any other tool key listed under POST /api/tool-run. Every job also exports as a spreadsheet at /api/tool-run/{job_id}/results.csv (or .xlsx).

Errors

All errors follow this shape:

{"detail": "Human-readable error"}
HTTPMeaning
400Missing or malformed param
401Bad / missing api key
403Tier doesn't allow this action
404Resource not found
408Job didn't finish in window
429Rate-limited — see Retry-After
500Server error — retry
503Database / upstream model unavailable

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

maps products webemail websearch fb fbads gads adleads twitter instagram yt yt_comp yt_tx email disposable dl_yt dl_ig dl_tt dl_fb dl_sn

An unrecognised key is rejected with 400 and a “did you mean” list before anything is charged — it never becomes a job that fails later. reddit, tiktok, linkedin and mapsrev are retired and answer 410. 

curl -X POST https://convertfleet.online/api/tool-run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "maps",
    "params": {
      "prompt": "50 lawyers in NYC",
      "max_results": 50,
      "deep_scan": false
    }
  }'

Response:

{
  "job_id":      "a1b2c3d4e5",
  "status":      "running",
  "tool":        "maps",
  "status_url":  "/api/tool-run/a1b2c3d4e5/status",
  "results_url": "/api/tool-run/a1b2c3d4e5/results",
  "poll_seconds": 5
}

Google Maps also still accepts POST /api/scrape with the same fields at the top level (no params wrapper); it returns the same job_id and is read back through the very same status / results endpoints.

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

Poll this until status is done.

curl https://convertfleet.online/api/tool-run/JOB_ID/status \
  -H "x-api-key: YOUR_API_KEY"
{
  "job_id":      "a1b2c3d4e5",
  "tool":        "maps",
  "status":      "running",      // running | done | error
  "records":     42,             // climbs while the scrape runs
  "stage":       "Scrolling results…",
  "has_results": false,          // true once /results will answer
  "done":        false,
  "error":       null,
  "warning":     null,           // why an empty run was empty
  "blocked":     false,          // the source refused us (not "no matches")
  "refunded":    false,
  "results_url": "/api/tool-run/a1b2c3d4e5/results"
}

job_id is echoed back so an automation can chain status → results straight off this response.

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

curl https://convertfleet.online/api/tool-run/JOB_ID/results \
  -H "x-api-key: YOUR_API_KEY"
{
  "job_id":  "a1b2c3d4e5",
  "tool":    "maps",
  "status":  "done",
  "count":   42,
  "results": [ { … }, { … } ]
}

Add ?offset=0&limit=200 to page through a big run. The same rows come back as a spreadsheet from /api/tool-run/{job_id}/results.csv and .xlsx.

Calling this before the job finishes answers 409 with a sentence naming the next call to make — not a bare 404. A 404 here means the run aged out of your plan’s retention window.

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", "…"],
  "engine_health_observed": true,
  "engines_working": ["bing"],
  "engines_blocked": ["brave", "google_html"],
  "engines_unconfigured": ["serper", "serpapi", "google_cse"],
  "engine_health": { "brave": { "ok": false, "kind": "blocked", "reason": "Brave returned HTTP 429", "age_s": 42 } },
  "recommended_engine": "auto",
  "note": "Real google.com rankings need SERPER_API_KEY, SERPAPI_KEY or GOOGLE_CSE_KEY + GOOGLE_CSE_CX (or a residential SEARCH_PROXY)…"
}

engine_health is measured, not assumed — every provider attempt is recorded, so it tracks blocks as they come and go. kind separates blocked (the engine refused us) from unconfigured (no API key set), because those need different fixes. engine_health_observed is false until the server has run at least one search since restart — treat an empty engines_working as "not measured yet", never as "everything is down".

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.

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