REST API

​

What it does

• Onboard new clients automatically. Hand the API a website URL. It researches the brand, proposes competitors and buyer-intent topics, and creates the project with prompts ready to scan.
• Run AI visibility scans across ChatGPT, Perplexity, Google AI Overviews, and DeepSeek. (Claude is gated to specific accounts.)
• Read visibility, share of voice, sentiment, citation sources, and per-attribute breakdowns programmatically.
• Download client-ready PDF reports.
• Manage projects, topics, prompts, and platforms.

​

Authentication

​

Get an API key

​

Send it on every request

Authorization: Bearer <your_api_key>

​

Base URL

https://openlens.com/api

​

End-to-end example

​

Setup

import json
import time
import requests

BASE = "https://openlens.com/api"
auth = {"Authorization": "Bearer YOUR_API_KEY"}

res = requests.post(
    f"{BASE}/onboard",
    headers=auth,
    json={"action": "analyze", "url": "https://anthropic.com/"},
)
analysis = json.loads(res.text.strip().split("data: ")[-1])["data"]

res = requests.post(f"{BASE}/onboard", headers=auth, json={
    "action": "confirm",
    "brandName": analysis["brandName"],
    "url": "https://anthropic.com/",
    "industryType": analysis["industryType"],
    "location": analysis["location"],
    "languages": analysis["languages"],
    "competitors": analysis["competitors"],
    "topicList": analysis["topics"],
    "activePlatforms": ["chatgpt_app", "perplexity_app", "google_app", "deepseek"],
    "promptsPerTopic": 10,
})
project_id = json.loads(res.text.strip().split("data: ")[-1])["data"]["projectId"]

run_id = requests.post(
    f"{BASE}/prompts/run",
    headers=auth,
    json={"projectId": project_id},
).json()["runId"]

while (s := requests.get(
    f"{BASE}/prompts/status",
    headers=auth,
    params={"projectId": project_id, "runId": run_id},
).json())["status"] not in ("completed", "failed"):
    time.sleep(30)

scores = requests.get(
    f"{BASE}/visibility",
    headers=auth,
    params={"projectId": project_id},
).json()

​

What you get back

Brand: Anthropic
Competitors: ['OpenAI', 'Google DeepMind', 'Meta AI', 'xAI', 'Mistral AI']
Topics: ['best large language model API for enterprise applications',
         'safest most reliable AI model for business',
         'top frontier AI models compared for developers']
  * Anthropic                  49.2%
    OpenAI                     55.8%
    Google DeepMind             5.8%
    Meta AI                     1.7%
    xAI                         5.8%
    Mistral AI                 14.2%

​

Supported platforms

​

Endpoint families

• Onboarding. POST /api/onboard (Server-Sent Events) with action: analyze or action: confirm.
• Runs. POST /api/prompts/run to start, GET /api/prompts/status to poll, DELETE /api/prompts/run to cancel, GET /api/prompts/results for raw responses. GET /api/prompts/runs lists a project’s run history (paginated, sortable, filterable); GET /api/prompts/runs/{runId} returns one run’s metadata and per-platform breakdown.
• Metrics. GET /api/visibility (overall, per-topic, per-attribute), GET /api/visibility/trends for time series, GET /api/insights/engines for per-platform source behavior, GET /api/insights/topic for an AI-generated insight paragraph.
• Citations. GET /api/brand-mentions-summary returns top cited URLs per topic. GET /api/sources returns top cited domains.
• Deliverables. GET /api/reports/runs returns completed run history. GET /api/reports/visibility?projectId=...&runId=... returns a client-ready PDF for one selected run.
• Resources. CRUD endpoints for projects, brands, topics, and prompts.
• Account. GET /api/me/limits, GET /api/usage, GET /api/settings/platforms. (Note: /api/settings/schedule returns 410 Gone. Scheduling is per-project now. Use /api/projects/{id}/schedule.)

runs = requests.get(
    f"{BASE}/prompts/runs",
    headers=auth,
    params={"projectId": project_id, "status": "completed"},
).json()
if not runs["runs"]:
    raise RuntimeError("No completed runs yet. Start a prompt run first.")
run_id = runs["runs"][0]["id"]

sources = requests.get(
    f"{BASE}/sources",
    headers=auth,
    params={"projectId": project_id, "runId": run_id},
).json()

​

Common errors

​

Support