…

7 min

Agent integration with the visible4ai API

An API key turns visible4ai into a tool your agent can call. Mint a key in your account, point your agent at POST /api/v1/analyse, and any audit you can run in the web UI is now a single HTTP call. This guide walks you from a fresh key to a working integration in Claude Code, Cursor, OpenAI Functions, LangChain, or plain fetch.

What you'll build

By the end of this page you'll have:

A working API key

Minted from your account page, revealed once, ready to drop into an env var or secret manager.

A first audit from the command line

One curl call returning a full visibility audit, the same shape the web UI uses.

An agent that can use it

Wired into your tool of choice with copy-pasteable snippets for the four most common runtimes.

Get an API key

Keys live on your account page. Each key is shown once at creation, then only its prefix is stored — losing it means revoking and minting a new one. Pro and Enterprise plans only.

Manage API keys →

Your first audit

Two ways to make your first call — pick whichever fits your workflow.

Open the API playground →or use the curl snippet below

Replace YOUR_KEY with the value you just minted, then run this from any terminal:

bash

curl -X POST https://visible4ai.com/api/v1/analyse \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

The response is the same JSON the web UI consumes — GEO score, file checks, E-E-A-T signals, citations, recommendations. Cached results carry _cached: true and an _cacheExpiresAt timestamp; pass "fresh": true in the body to force a re-crawl.

json

{
  "url": "https://example.com",
  "domain": "example.com",
  "geoScore": 67,
  "summary": "...",
  "files": { "llmsTxt": { "present": true }, "aiTxt": { "present": false } },
  "eeat": { "experience": "...", "expertise": "..." },
  "citations": { "perplexity": [...], "chatgpt": [...] },
  "recommendations": [ { "title": "...", "priority": "high" } ],
  "_cached": false
}

Wire it into your agent

Four ways to call the endpoint from agent runtimes, in rough order of how many of our customers use each:

Claude Code (env var + skill)

Add the key to your shell profile, then any skill or hook that runs curl picks it up automatically.

bash

# ~/.zshrc or ~/.bashrc
export VISIBLE4AI_API_KEY="v4a_live_..."

# Any skill or hook that runs curl will now pick it up:
curl -sS -X POST https://visible4ai.com/api/v1/analyse \
  -H "Authorization: Bearer $VISIBLE4AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"url\": \"$1\"}" | jq .

OpenAI Functions / tool calling

Declare a single tool the model can call. The schema is small because the endpoint only takes one parameter.

typescript

const tools = [{
  type: "function",
  function: {
    name: "analyse_url",
    description: "Run a visible4ai audit on a URL.",
    parameters: {
      type: "object",
      properties: {
        url: { type: "string", description: "Absolute URL to audit." },
      },
      required: ["url"],
    },
  },
}];

// When the model calls analyse_url with { url }:
const res = await fetch("https://visible4ai.com/api/v1/analyse", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VISIBLE4AI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: args.url }),
});

LangChain Tool

Wrap the fetch in a Tool and pass it to your agent — Python or JS.

python

from langchain_core.tools import tool
import os, requests

@tool
def analyse_url(url: str) -> dict:
    """Run a visible4ai audit on the given URL."""
    r = requests.post(
        "https://visible4ai.com/api/v1/analyse",
        headers={"Authorization": f"Bearer {os.environ['VISIBLE4AI_API_KEY']}"},
        json={"url": url},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Plain fetch (TypeScript or Python)

When no framework is involved, the raw HTTP call works everywhere. This is also the easiest way to test that your key is live before plumbing it into a larger agent.

typescript

async function analyseUrl(url: string) {
  const res = await fetch("https://visible4ai.com/api/v1/analyse", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VISIBLE4AI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url }),
  });
  if (!res.ok) throw new Error(`visible4ai ${res.status}`);
  return res.json();
}

python

import os, requests

def analyse_url(url: str):
    r = requests.post(
        "https://visible4ai.com/api/v1/analyse",
        headers={"Authorization": f"Bearer {os.environ['VISIBLE4AI_API_KEY']}"},
        json={"url": url},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Reference

Endpoint

POST /api/v1/analyse

Authentication

Authorization: Bearer v4a_live_…

Rate limit

100 requests per 15-minute window, 1000 per 24-hour window, per key. 429 returns a Retry-After header in seconds.

Body

{ "url": "https://example.com", "fresh"?: boolean } — max 16 KB.

Error codes

401 UNAUTHORIZED — missing, invalid, or revoked key
403 PLAN_REQUIRED — account is on Free or has been downgraded
400 INVALID_URL — URL missing, malformed, or blocked
429 RATE_LIMITED — slow down; honour Retry-After
413 PAYLOAD_TOO_LARGE — request body exceeded 16 KB
502 ENGINE_ERROR — transient crawl or analysis failure; retry

🔒We never log your key

Every server-side log line is run through a bearer-redaction helper before it can hit a sink. If a future code path accidentally tries to log your token, our test suite fails the build. The verified shape of your key, sha256-hashed, is the only thing we store after creation.

Endpoint Context Protocol (ECP) integration

7 min

Agent integration with the visible4ai API

What you'll build

By the end of this page you'll have:

A working API key

Minted from your account page, revealed once, ready to drop into an env var or secret manager.

A first audit from the command line

One curl call returning a full visibility audit, the same shape the web UI uses.

An agent that can use it

Wired into your tool of choice with copy-pasteable snippets for the four most common runtimes.

Get an API key

Keys live on your account page. Each key is shown once at creation, then only its prefix is stored — losing it means revoking and minting a new one. Pro and Enterprise plans only.

Manage API keys →

Your first audit

Two ways to make your first call — pick whichever fits your workflow.

Open the API playground →or use the curl snippet below

Replace YOUR_KEY with the value you just minted, then run this from any terminal:

bash

curl -X POST https://visible4ai.com/api/v1/analyse \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

json

{
  "url": "https://example.com",
  "domain": "example.com",
  "geoScore": 67,
  "summary": "...",
  "files": { "llmsTxt": { "present": true }, "aiTxt": { "present": false } },
  "eeat": { "experience": "...", "expertise": "..." },
  "citations": { "perplexity": [...], "chatgpt": [...] },
  "recommendations": [ { "title": "...", "priority": "high" } ],
  "_cached": false
}

Wire it into your agent

Four ways to call the endpoint from agent runtimes, in rough order of how many of our customers use each:

Claude Code (env var + skill)

Add the key to your shell profile, then any skill or hook that runs curl picks it up automatically.

bash

# ~/.zshrc or ~/.bashrc
export VISIBLE4AI_API_KEY="v4a_live_..."

# Any skill or hook that runs curl will now pick it up:
curl -sS -X POST https://visible4ai.com/api/v1/analyse \
  -H "Authorization: Bearer $VISIBLE4AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"url\": \"$1\"}" | jq .

OpenAI Functions / tool calling

Declare a single tool the model can call. The schema is small because the endpoint only takes one parameter.

typescript

const tools = [{
  type: "function",
  function: {
    name: "analyse_url",
    description: "Run a visible4ai audit on a URL.",
    parameters: {
      type: "object",
      properties: {
        url: { type: "string", description: "Absolute URL to audit." },
      },
      required: ["url"],
    },
  },
}];

// When the model calls analyse_url with { url }:
const res = await fetch("https://visible4ai.com/api/v1/analyse", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VISIBLE4AI_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ url: args.url }),
});

LangChain Tool

Wrap the fetch in a Tool and pass it to your agent — Python or JS.

python

from langchain_core.tools import tool
import os, requests

@tool
def analyse_url(url: str) -> dict:
    """Run a visible4ai audit on the given URL."""
    r = requests.post(
        "https://visible4ai.com/api/v1/analyse",
        headers={"Authorization": f"Bearer {os.environ['VISIBLE4AI_API_KEY']}"},
        json={"url": url},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Plain fetch (TypeScript or Python)

When no framework is involved, the raw HTTP call works everywhere. This is also the easiest way to test that your key is live before plumbing it into a larger agent.

typescript

async function analyseUrl(url: string) {
  const res = await fetch("https://visible4ai.com/api/v1/analyse", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.VISIBLE4AI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ url }),
  });
  if (!res.ok) throw new Error(`visible4ai ${res.status}`);
  return res.json();
}

python

import os, requests

def analyse_url(url: str):
    r = requests.post(
        "https://visible4ai.com/api/v1/analyse",
        headers={"Authorization": f"Bearer {os.environ['VISIBLE4AI_API_KEY']}"},
        json={"url": url},
        timeout=120,
    )
    r.raise_for_status()
    return r.json()

Reference

Endpoint

POST /api/v1/analyse

Authentication

Authorization: Bearer v4a_live_…

Rate limit

100 requests per 15-minute window, 1000 per 24-hour window, per key. 429 returns a Retry-After header in seconds.

Body

{ "url": "https://example.com", "fresh"?: boolean } — max 16 KB.

Error codes

401 UNAUTHORIZED — missing, invalid, or revoked key
403 PLAN_REQUIRED — account is on Free or has been downgraded
400 INVALID_URL — URL missing, malformed, or blocked
429 RATE_LIMITED — slow down; honour Retry-After
413 PAYLOAD_TOO_LARGE — request body exceeded 16 KB
502 ENGINE_ERROR — transient crawl or analysis failure; retry

🔒We never log your key

Endpoint Context Protocol (ECP) integration