API Reference

Complete reference for the WebPerception API. Extract data, capture screenshots, and analyze pages with AI.

Base URL: https://api.mantisapi.com

Authentication
Core Endpoints
GET /health
POST /extract
POST /screenshot
POST /extract/ai
POST /signup
Billing Endpoints
GET /billing/plans
POST /billing/checkout
GET /billing/usage
POST /billing/portal
Reference
Plans & Pricing
Error Codes
For AI Agents

Authentication

All API requests (except /health and GET /billing/plans) require an API key passed in the x-api-key header.

curl -H "x-api-key: YOUR_API_KEY" https://api.mantisapi.com/health

Don't have a key? Sign up free — 100 requests/month on the free plan.

Core Endpoints

GET /health

Check API status. No authentication required.

Response

{
  "status": "ok",
  "service": "webperception-api",
  "version": "1.0.0"
}

POST /extract

Extract structured content from any URL — title, text, links, images, and metadata.

Request Body

Field	Type	Required	Description
`url`	string	Yes	URL to extract content from

Example

curl -X POST https://api.mantisapi.com/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://example.com"}'

Response

{
  "title": "Example Domain",
  "text": "This domain is for use in illustrative examples...",
  "links": ["https://www.iana.org/domains/example"],
  "images": [],
  "metadata": {
    "description": "",
    "keywords": ""
  }
}

POST /screenshot

Capture a full-page screenshot of any URL. Returns a PNG image URL valid for 24 hours.

Request Body

Field	Type	Required	Description
`url`	string	Yes	URL to screenshot

Example

curl -X POST https://api.mantisapi.com/screenshot \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"url": "https://example.com"}'

Response

{
  "screenshotUrl": "https://webperception-screenshots-....s3.amazonaws.com/...",
  "url": "https://example.com"
}

POST /extract/ai

AI-powered extraction — pass a natural language prompt to extract specific data from any page using LLM analysis.

Request Body

Field	Type	Required	Description
`url`	string	Yes	URL to analyze
`prompt`	string	Yes	What to extract (e.g., "Get all product prices and names")

Example

curl -X POST https://api.mantisapi.com/extract/ai \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "url": "https://news.ycombinator.com",
    "prompt": "Extract the top 5 story titles and their scores"
  }'

Note: The /extract/ai endpoint uses more compute and counts as 5 requests toward your monthly limit.

POST /signup

Create a free account and get an API key instantly. No credit card required.

Request Body

Field	Type	Required	Description
`email`	string	Yes	Your email address

Example

curl -X POST https://api.mantisapi.com/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Response

{
  "message": "Account created successfully",
  "apiKey": "wp_...",
  "plan": "free",
  "monthlyLimit": 100
}

Billing Endpoints

GET /billing/plans

List all available plans with pricing, limits, and features. No authentication required.

Example

curl https://api.mantisapi.com/billing/plans

Response

{
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "price": 0,
      "monthlyLimit": 100,
      "features": ["Screenshot capture", "Content extraction", "100 requests/month"]
    },
    {
      "id": "starter",
      "name": "Starter",
      "price": 29,
      "monthlyLimit": 5000,
      "overage": 0.005,
      "features": ["Everything in Free", "5,000 requests/month", "AI extraction", "$0.005/request overage"]
    },
    {
      "id": "pro",
      "name": "Pro",
      "price": 99,
      "monthlyLimit": 25000,
      "overage": 0.005,
      "features": ["Everything in Starter", "25,000 requests/month", "Priority support"]
    },
    {
      "id": "scale",
      "name": "Scale",
      "price": 299,
      "monthlyLimit": 100000,
      "overage": 0.005,
      "features": ["Everything in Pro", "100,000 requests/month", "Dedicated support"]
    }
  ]
}

POST /billing/checkout

Create a Stripe Checkout session to upgrade your plan. Returns a redirect URL.

Request Body

Field	Type	Required	Description
`plan`	string	Yes	Plan ID: `starter`, `pro`, or `scale`

Example

curl -X POST https://api.mantisapi.com/billing/checkout \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"plan": "starter"}'

Response

{
  "checkoutUrl": "https://checkout.stripe.com/c/pay/...",
  "sessionId": "cs_..."
}

GET /billing/usage

Get your current usage stats — plan, requests used, limit, and billing period.

Example

curl https://api.mantisapi.com/billing/usage \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "plan": "starter",
  "currentUsage": 1247,
  "monthlyLimit": 5000,
  "usageResetAt": "2026-04-01T00:00:00.000Z",
  "overage": 0.005
}

POST /billing/portal

Get a Stripe Customer Portal link to manage your subscription, update payment method, or cancel.

Note: Only available for paid plan subscribers.

Example

curl -X POST https://api.mantisapi.com/billing/portal \
  -H "x-api-key: YOUR_API_KEY"

Response

{
  "portalUrl": "https://billing.stripe.com/p/session/..."
}

Plans & Pricing

Plan	Requests/Month	Price	Overage
Free	100	$0	—
Starter	5,000	$29/mo	$0.005/req
Pro	25,000	$99/mo	$0.005/req
Scale	100,000	$299/mo	$0.005/req

Overage is billed automatically at the end of each billing period via Stripe metered billing.

Error Codes

Code	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Missing or invalid API key
`403`	Feature not available on your plan
`409`	Email already registered (signup)
`429`	Monthly request limit exceeded (upgrade or wait for reset)
`500`	Internal server error — try again or contact support

For AI Agents

WebPerception API is purpose-built for autonomous AI agents. Here's a complete integration flow:

# 1. Sign up programmatically
API_KEY=$(curl -s -X POST https://api.mantisapi.com/signup \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@yourapp.com"}' | jq -r '.apiKey')

# 2. Check available plans
curl -s https://api.mantisapi.com/billing/plans | jq '.plans'

# 3. Extract data from any page
curl -s -X POST https://api.mantisapi.com/extract \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{"url": "https://target-site.com"}'

# 4. AI-powered extraction with natural language
curl -s -X POST https://api.mantisapi.com/extract/ai \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d '{
    "url": "https://news.ycombinator.com",
    "prompt": "Get the top 10 stories with titles, URLs, and point counts"
  }'

# 5. Check your usage
curl -s https://api.mantisapi.com/billing/usage \
  -H "x-api-key: $API_KEY"

Python SDK Example

import requests

API_KEY = "wp_..."
BASE = "https://api.mantisapi.com"
headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}

# Extract content
resp = requests.post(f"{BASE}/extract", headers=headers, json={"url": "https://example.com"})
data = resp.json()
print(data["title"], len(data["links"]), "links found")

# AI extraction
resp = requests.post(f"{BASE}/extract/ai", headers=headers, json={
    "url": "https://news.ycombinator.com",
    "prompt": "Extract top 5 stories with titles and scores"
})
print(resp.json())

JavaScript/Node.js Example

const API_KEY = "wp_...";
const BASE = "https://api.mantisapi.com";

const res = await fetch(`${BASE}/extract`, {
  method: "POST",
  headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
  body: JSON.stringify({ url: "https://example.com" })
});
const data = await res.json();
console.log(data.title, data.links.length, "links");

API Reference

Contents

Authentication

Core Endpoints

Response

Request Body

Example

Response

Request Body

Example

Response

Request Body

Example

Request Body

Example

Response

Billing Endpoints

Example

Response

Request Body

Example

Response

Example

Response

Example

Response

Plans & Pricing

Error Codes

For AI Agents

Python SDK Example

JavaScript/Node.js Example