SwipeAgent API

Quickstart#

Ask your first question in one request — the agent researches and answers with structured findings.

curl https://swipeagent.ai/api/v1/agent \
  -H "X-Api-Key: vb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "What are the top trending TikTok Shop products this week?"}'

Authentication#

API and CLI requests authenticate with the X-Api-Key header; for MCP clients, see How each client connects below. Keys are shown once at creation — store them like passwords.

X-Api-Key: vb_live_your_key_here

Agent API#

POST /api/v1/agent — ask the research agent anything in natural language. It runs the same tool stack as in-app chat — video/product/creator search, trends, transcripts, AI video descriptions — and returns a synthesized answer with structured findings. Requests are stateless; for multi-turn conversations, send the prior exchange back as messages.

Request body

• prompt — a single question (string). Provide exactly one of prompt or messages.
• messages — conversation history: [{"role": "user" | "assistant", "content": "..."}]
• source — optional content scope: all (default), shop (TikTok Shop), apps, physical, digital

Example

curl https://swipeagent.ai/api/v1/agent \
  -H "X-Api-Key: vb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Find UGC-style videos promoting language learning apps with strong hooks"}
    ],
    "source": "apps"
  }'

Response

{
  "answer": "Here are the strongest matches...",
  "findings": {
    "videos":   [ { "video_id": "...", "title": "...", "views": 123456, "creator": "..." } ],
    "products": [],
    "creators": []
  },
  "suggestions": ["Compare their hooks", "Track these creators"],
  "usage": {
    "credits_charged": 1.25,
    "input_tokens": 15230,
    "output_tokens": 2048,
    "tool_calls": 4
  }
}

Errors#

• 400 — invalid body (the error message says what to fix)
• 401 — missing or invalid API key
• 402 — credit balance empty (top up in the app)
• 429 — rate limited; retry after retry_after_s

MCP Server#

Use SwipeAgent inside Claude, Cursor & friends. The MCP server exposes a research tool — ask_swipeagent — which runs the full SwipeAgent agent on your question and returns a written answer plus structured findings. Ask for what you want in plain language rather than composing searches yourself; the agent decides which lookups to run, and can manage your alerts too. Streamable HTTP transport.

Longer research returns status: running and a run_id. Call get_result with that ID every 20–30 seconds until it completes; do not repeat the question to check progress. Typical runs take 3–10 minutes. Polling is free. Completed runs are charged once; interrupted runs are not charged. Only you can read your results.

Server URL

https://swipeagent.ai/api/mcp

Claude Code

claude mcp add --transport http swipeagent https://swipeagent.ai/api/mcp \
  --header "x-api-key: vb_live_your_key_here"

CLI#

SwipeAgent in your terminal.

npm i -g swipeagent
sa login vb_live_your_key_here
sa "which teeth whitening products are blowing up this week?"

• Conversations persist between invocations; sa reset starts fresh.
• --json prints the raw response for scripts.
• Env overrides: SWIPEAGENT_API_KEY, SWIPEAGENT_BASE_URL.

Usage & Fair Use#

• Agent requests are metered in credits against your subscription (the usage block reports each request's cost). Your balance and per-key usage live at /dev.
• Per-key rate limits sit far above human research pace; bulk extraction hits them quickly. Daily data budgets apply to how many distinct creators a key can sweep.
• The former REST data endpoints (/api/v1/videos, /products, …) are retired; the same key works on everything documented here.