AI Visibility Scout

Authentication

Every request carries a per-site API key (minted in the Scout admin) in the x-api-key header. Account-level keys that own several sites pass ?site=<domain> to pick one. Apps on the Bitline VPS call over localhost (http://127.0.0.1:3012); external tenants use https://www.webvisibility.io.

x-api-key: blk_yoursite_…

GET/api/v1/targets?site=<domain>&limit=7&status=pending

Your ordered content/keyword queue — highest priority first. Statuses: pending, queued, generating, generated, failed, paused (default filter: pending+queued).

curl "http://127.0.0.1:3012/api/v1/targets?site=velocitybanking.io&limit=7" \
  -H "x-api-key: $BITLINE_API_KEY"

// → { "site": "velocitybanking.io", "targets": [
//     { "id": "…", "external_id": "vb-123", "keyword": "velocity banking calculator",
//       "intent": "calculator", "priority": 90, "target_url": null,
//       "notes": null, "status": "pending",
//       "search_volume": 1200, "difficulty": 35 } ] }

POST/api/v1/targets

Upsert queue rows — idempotent by site+keyword, so re-syncing your computed queue is always safe. Max 500 per call.

curl -X POST "http://127.0.0.1:3012/api/v1/targets?site=velocitybanking.io" \
  -H "x-api-key: $BITLINE_API_KEY" -H "content-type: application/json" \
  -d '{"targets":[{"keyword":"velocity banking calculator",
       "intent":"calculator","priority":90,"external_id":"vb-123"}]}'

POST/api/v1/targets/:id/result

Report what happened to a target you pulled. Idempotent — safe to retry. Body-addressed alias: POST /api/v1/targets/results with external_id when you don't track Scout ids.

curl -X POST "http://127.0.0.1:3012/api/v1/targets/TARGET_ID/result?site=velocitybanking.io" \
  -H "x-api-key: $BITLINE_API_KEY" -H "content-type: application/json" \
  -d '{"status":"generated","post_id":"blog-post-slug"}'

TypeScript SDK (~40-line integration)

On the Bitline VPS, import the shared client from /opt/projects/bitline-sdk — auth, retries, and idempotency handled.

import { BitlineClient } from "/opt/projects/bitline-sdk/index.ts";

const brain = new BitlineClient({
  baseUrl: "http://127.0.0.1:3012",
  apiKey: process.env.BITLINE_API_KEY!,
  site: "velocitybanking.io",
});

// 1. fetch this week's queue (falls back to your local computation if down)
const { targets } = await brain.getTargets({ limit: 7 });

// 2. generate content your way (local claude CLI), then report back
await brain.reportTargetResult({
  external_id: targets[0].external_id ?? undefined,
  id: targets[0].id,
  status: "generated",
  post_id: "the-published-slug",
});

Errors

401 — missing/invalid/revoked key
400 — bad payload, or account key without ?site=
404 — result posted for an unknown target
Retry 429/5xx with backoff — all writes are idempotent.

Platform API

Authentication

TypeScript SDK (~40-line integration)

Errors