---
name: swipeagent
description: >
  Research TikTok at scale through the SwipeAgent API: trending videos and
  the hooks behind them, creators promoting a niche, TikTok Shop products on
  the rise, transcripts, and competitor breakdowns. Use whenever the user
  asks about TikTok trends, viral content, UGC ads, TikTok Shop products,
  or short-form creator research.
---

# SwipeAgent

SwipeAgent watches TikTok at scale — millions of videos, the creators behind
them, and the products they sell, enriched with transcripts and AI
understanding. This skill calls its research agent over HTTP.

## Authentication

Every request authenticates with the `X-Api-Key` header. Ask the user for
their key if you don't have one (created at https://swipeagent.ai/dev —
requires a SwipeAgent subscription). Treat keys like passwords: never echo
them back or store them in files.

## Ask the agent

One endpoint does the research: describe what you want in natural language.

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

Request body:

- `prompt` — a single question (string). Provide exactly one of `prompt` or
  `messages`.
- `messages` — conversation history for multi-turn research:
  `[{"role": "user" | "assistant", "content": "..."}]`. Requests are
  stateless — send the prior exchange back yourself.
- `source` — optional content scope: `all` (default), `shop` (TikTok Shop),
  `apps`, `physical`, `digital`.

Response shape:

```json
{
  "answer": "Synthesized answer...",
  "findings": { "videos": [], "products": [], "creators": [] },
  "suggestions": ["Follow-up ideas"],
  "usage": { "credits_charged": 1.25, "input_tokens": 15230, "output_tokens": 2048, "tool_calls": 4 }
}
```

Lead with `answer` when reporting back; cite concrete items from `findings`
(views, creators, product names) rather than paraphrasing vaguely.

## Errors

- `400` — invalid body; the error message says what to fix.
- `401` — missing or invalid API key; ask the user to re-check it.
- `402` — credit balance empty; the user tops up in the app.
- `429` — rate limited; wait `retry_after_s` seconds, then retry once.

## MCP alternative

If the host supports MCP, the same capability is available as a server —
often the better integration:

```bash
claude mcp add --transport http swipeagent https://swipeagent.ai/api/mcp \
  --header "x-api-key: $SWIPEAGENT_API_KEY" \
  --header "x-swipeagent-client: mcp"
```

## Good questions to send it

- "Find UGC-style videos promoting language learning apps with strong hooks"
- "Which teeth-whitening products are blowing up this week?"
- "Break down why @creator's top video works — hook, structure, CTA"
- "Who are the fastest-growing creators selling supplements?"