# Papalily

> AI-powered web scraping and browser automation API. Renders any website with a real Chromium browser and extracts structured JSON — or executes interactive tasks across multiple pages.

Papalily is a REST API that accepts a URL and either a plain-English prompt (for static extraction) or interactive steps/tasks (for dynamic sites). It renders pages with a real Chromium browser, supports JavaScript-heavy SPAs, and uses Gemini AI vision to extract clean structured JSON.

## Key Facts
- Base URL: https://api.papalily.com
- Authentication: x-api-key header (from RapidAPI subscription)
- RapidAPI listing: https://rapidapi.com/andognet/api/papalily
- No CSS selectors required — describe data in plain English
- Handles JavaScript-rendered pages (SPA, React, Vue, Next.js, Angular)
- Supports interactive workflows: form fills, clicks, pagination, logins
- Average response time: 8–15 seconds
- Results cached 10 minutes (cache hits don't count against quota)
- Current version: v1.3.0

## Pricing
- Basic: $0/month — 50 requests (no sessions)
- Pro: $20/month — 1,000 requests + 3 concurrent sessions
- Ultra: $100/month — 20,000 requests + 10 concurrent sessions
- Mega: $300/month — 100,000 requests + 20 concurrent sessions

## Endpoints

### POST /scrape
Static extraction — loads a URL, takes a screenshot, extracts data with AI vision.
- url (required): Target URL
- prompt (required): Plain-English description of data to extract
- proxy_url (optional): Proxy for geo-targeted requests
- no_cache (optional): Bypass cache

### POST /interact
Interactive browser automation — execute steps on a live page.
Accepts either explicit steps or a plain-English task (AI plans the steps automatically).
- url (required): Starting URL
- task (string): Plain-English goal — AI generates and executes steps
- steps (array): Explicit step array

Step types:
- { "js": "<JS string>", "wait_for": "<selector>", "wait_ms": <ms> } — execute JavaScript
- { "navigate": "<url>" } — navigate to URL
- { "wait_for": "<selector>", "wait_ms": <ms> } — wait only
- { "css_schema": { "base": "<selector>", "fields": [...] } } — zero-AI CSS extraction
- { "extract": "<prompt>" } — AI vision extraction
- { "screenshot": true } — capture page as JPEG

### POST /session/start
Start a persistent browser session. Browser stays alive between API calls.
Available on Pro plan and above.
- url (required): Starting URL

### POST /session/:id/step
Execute one step or a task on a live session.
- Accepts same step types as /interact steps, or { "task": "..." } for AI-planned multi-step

### GET /session/:id/state
Get current session page URL, title, screenshot, and TTL remaining.

### DELETE /session/:id
Close session and free browser resources. Sessions auto-expire after 10 min idle.

### GET /usage
Returns plan, requests used, and remaining quota.

### GET /health
Health check. No auth required.

### GET /status/:requestId
Look up a past request by ID.

## Example Usage

### Static scrape
POST https://api.papalily.com/scrape
{"url": "https://example.com", "prompt": "Get all product names and prices"}

### Interactive task (natural language)
POST https://api.papalily.com/interact
{"url": "https://news.ycombinator.com", "task": "Get the top 10 post titles with URLs and scores"}

### Interactive steps (explicit)
POST https://api.papalily.com/interact
{"url": "https://news.ycombinator.com", "steps": [
  {"css_schema": {"base": "tr.athing", "fields": [{"name": "title", "selector": ".titleline a", "type": "text"}]}},
  {"js": "document.querySelector('a.morelink').click()", "wait_for": "tr.athing", "wait_ms": 1000},
  {"extract": "All post titles and URLs from page 2"}
]}

### Persistent session
POST /session/start → {"url": "https://site.com"}
POST /session/:id/step → {"js": "...", "wait_for": "..."}
POST /session/:id/step → {"extract": "..."}
DELETE /session/:id

## Links
- [Documentation](https://www.papalily.com/docs.html)
- [Pricing](https://www.papalily.com/pricing.html)
- [Blog](https://www.papalily.com/blog/)
- [Changelog](https://www.papalily.com/changelog.html)
- [RapidAPI Listing](https://rapidapi.com/andognet/api/papalily)
- [Terms of Use](https://www.papalily.com/terms.html)