AI Agent Integration

Use the Virlo API from Cursor, Claude Code, OpenClaw, Windsurf, or any AI assistant that can call APIs or connect via MCP. This page is for developers setting that up — not instructions for the assistant itself (those live in the plain-text files below).

LLM-Optimized Documentation

We publish plain-text, markdown-formatted API documentation specifically designed for LLM consumption — no CSS, JavaScript, or navigation to parse.

How to load these files in your assistant

Paste a URL in chat, add it to project rules, or @-mention the file. Examples:

• OpenClaw / Claude Code: "Read https://dev.virlo.ai/llms-full.txt and use the Virlo API to research trending TikTok content"
• Cursor: Reference the URL in chat or paste the content for context
• Any agent with web access: The agent can fetch and parse these files directly

OpenClaw Skill

Install the Short-Form Market Research Brain skill from ClawHub so OpenClaw / Claude Code gets built-in Virlo API expertise.

clawhub install short-form-market-research-brain ```
</CodeGroup>

### Configuration

After installation, configure your API key:

<CodeGroup title="Configure API Key">
```bash {{ title: 'Configure' }}
openclaw config set short-form-market-research-brain.api_key
"virlo_tkn_YOUR_KEY" ```
</CodeGroup>

### What the Skill Provides

The skill teaches the assistant to:

- Search for any topic across TikTok, YouTube, and Instagram with keyword research
- Get AI-generated social intelligence reports with strategic insights
- Find rising creators who outperform their follower count
- Track trending topics, hashtags, and viral videos in real-time
- Set up automated niche monitoring on recurring schedules
- Analyze individual creator profiles and video performance
- Monitor creators and videos over time with configurable scrape cadences and AI reports
- Discover trending sounds, search by title, analyze sound adoption velocity, and find creator sound catalogs
- Manage credit balance awareness and recommend optimal workflows

### Example Prompts

Once installed, try prompts like:

- "Research the TikTok Shop niche and give me a trend report"
- "Find creators making content about personal injury law"
- "What's trending on social media today?"
- "Analyze @username on TikTok — how are they performing?"
- "Set up weekly monitoring for wedding photography content"
- "Start tracking @khaby.lame on TikTok with 12-hour scrape cadence"
- "Show me the growth snapshots for my tracked creators"
- "What sounds are trending on TikTok right now?"
- "Search for sounds related to 'lofi beats' and show me which ones are commerce-safe"
- "Show me the usage history for this sound — is it gaining or losing momentum?"
- "What sounds does @artist_name own and how much UGC do they drive?"

---

## MCP Configuration {{ id: 'mcp-configuration' }}

Virlo provides a **native MCP server** with 30 curated tools — no third-party proxy needed. See the [MCP Server](/docs/mcp) page for one-click setup.

You can also connect via tools like <a href="https://openapi2mcp.com" target="_blank" rel="noopener noreferrer">openapi2mcp</a> or <a href="https://www.restmcp.io/" target="_blank" rel="noopener noreferrer">RestMCP</a> using the OpenAPI spec.

### Auto-Generate MCP Server from OpenAPI

<CodeGroup title="Auto-Generate MCP Server">
```bash {{ title: 'Generate' }}
npx openapi2mcp https://api.virlo.ai/openapi.json ```
</CodeGroup>

### Manual MCP Configuration

Add to your MCP config (e.g., `openclaw.json` or Cursor MCP settings):

<CodeGroup title="MCP Configuration">
```json {{ title: 'openclaw.json' }}
{
"mcpServers": {
  "virlo": {
    "command": "npx",
    "args": ["openapi2mcp", "https://api.virlo.ai/openapi.json"],
    "env": {
      "API_KEY": "virlo_tkn_YOUR_KEY"
    }
  }
}
}

OpenAPI Specification

The full OpenAPI 3.0 specification is available as JSON at https://api.virlo.ai/openapi.json.

This spec is auto-generated from the API source code and always reflects the current endpoint definitions. Use it with:

• Swagger UI: Interactive exploration at https://api.virlo.ai/api
• Code generators: Generate typed clients in any language
• MCP converters: Auto-generate MCP servers for AI agents
• API testing tools: Import directly into Postman, Insomnia, etc.

Tips when using an AI assistant

Getting the Best Results

0. Add the Agent Playbook to your assistant's context (or point it at /agent-playbook.txt). It covers which workflow to run for each question and how to interpret results — things endpoint schemas alone don't teach.

1. Use specific keywords in your prompts. "Research jeep wrangler mods" works far better than "research jeep". Multi-word phrases dramatically improve result quality.

2. Request the full workflow. Ask for a "full niche analysis" rather than just "search for X" — that pulls AI reports, videos, ads, and creator outliers, not just a keyword queue.

3. Include all platforms. Unless you specifically need data from one platform, include YouTube, TikTok, and Instagram for the most comprehensive results.

4. AI analysis is automatic. Every Orbit search now includes AI analysis and trend detection at no extra cost. The results are available via the /analysis and /trends sub-endpoints once the job completes.

Async Workflow Awareness

Several Virlo endpoints are asynchronous (Orbit keyword search, Satellite creator lookup, Satellite video analysis, batch creator lookup, and post collection). Tell your assistant to:

1. Queue the job and save the returned ID
2. Poll until finalized: true — not just status: "completed", which can return before AI analysis finishes (see Async Data Model)
3. Treat partial_failure as usable data (one platform failed, the rest succeeded)
4. Never set hard timeouts — Orbit/Comet runs often take 15–45 minutes

Credit Management

• Check X-Credits-Remaining after each request
• Retrieval endpoints (videos, slideshows, ads, outliers, analysis, trends, sounds from Orbit/Comet, tracking GET/PATCH/DELETE, posting cadence, creator posts) are always free
• The most expensive operations are 50 credits ($0.50) — Orbit search, Comet creation, Satellite lookup/analysis
• Tracking cycles (creator or video) cost 25 credits ($0.25) each — includes metrics collection and AI report generation
• Post collection costs vary by depth: standard ($0.50), deep ($1.00), full ($2.00)
• Purchase credits at virlo.ai/pricing when running low