API Reference

All API endpoints are prefixed with /api/v1. Responses are always JSON. The API is available exclusively to Enterprise plan subscribers.

New to the API? Browse the quickstart guides for end-to-end tutorials with curl, JavaScript, and Python examples.

Quick start

curl https://www.linksii.com/api/v1/workspaces \
  -H "Authorization: Bearer lnk_your_api_key_here"

Every request must include your API key as a Bearer token in the Authorization header. API keys start with lnk_ and are shown only once at creation time — store them securely.

Header format

Authorization: Bearer lnk_a1b2c3d4e5f6...

Generating keys

Keys are managed from Settings → API Keys or via the POST /api/v1/keys endpoint. Each workspace supports up to 10 active keys.

Rate limits are enforced per API key. Every response includes headers showing your current usage.

Response headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 94
X-RateLimit-Reset: 1710000060

Per-endpoint limits

Exceeding a limit returns 429 Too Many Requests with a Retry-After header. The /api/v1/analyze endpoint also enforces a daily quota of 500 analyses per key (resets at midnight UTC).

Error format

All errors return a JSON body with an error string. Some errors include a machine-readable code.

{
  "error": "workspace_id is required",
  "code": "MISSING_PARAM"   // optional
}

HTTP status codes

Pagination

List endpoints accept limit (1–100, default 20) and offset (default 0) query parameters. Responses include a meta object:

{
  "data": [...],
  "meta": {
    "total": 143,
    "limit": 20,
    "offset": 0
  }
}

Workspaces represent the brands you are tracking. All other resources (prompts, competitors, tracking results) belong to a workspace.

List all workspaces accessible to the authenticated API key (owned or accepted member).

Query parameters

Example

curl "https://www.linksii.com/api/v1/workspaces?limit=10" \
  -H "Authorization: Bearer lnk_your_key"

Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "brand_name": "Acme Corp",
      "domain": "acme.com",
      "description": "B2B SaaS for project management",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-03-01T08:30:00Z"
    }
  ],
  "meta": { "total": 3, "limit": 10, "offset": 0 }
}

Create a new workspace. Useful for spinning up temp workspaces for prospect audits. Respects your plan's workspace limit.

Request body

Response (201)

{
  "data": {
    "id": "uuid",
    "brand_name": "Example Clinic",
    "domain": "exampleclinic.com",
    "description": "...",
    "location": "Belfast, UK",
    "country": "GB",
    "created_at": "2026-04-21T09:00:00Z",
    "updated_at": "2026-04-21T09:00:00Z"
  }
}

Soft-delete a workspace. Only the workspace owner can delete. Returns 204 No Content on success. Useful for cleaning up temporary prospect workspaces.

Tracking results capture how your brand appears across AI platforms (Claude, ChatGPT, Gemini, Perplexity) for each prompt you monitor.

Fetch tracking results for a workspace with optional filtering by platform, date range, and pagination.

Query parameters

Example

curl "https://www.linksii.com/api/v1/tracking?workspace_id=WORKSPACE_ID&days=7&platform=chatgpt" \
  -H "Authorization: Bearer lnk_your_key"

Response

{
  "data": [
    {
      "id": "uuid",
      "prompt_id": "uuid",
      "workspace_id": "uuid",
      "ai_platform": "chatgpt",
      "brand_mentioned": true,
      "brand_visibility_pct": 85.5,
      "brand_position": 2,
      "brand_ordinal_position": 2,
      "brand_relative_position": 0.18,
      "brand_appearance_count": 3,
      "sentiment_score": 0.72,
      "sentiment_label": "positive",
      "mention_type": "direct",
      "sources_cited": ["https://techcrunch.com/..."],
      "competitor_mentions": ["Salesforce", "HubSpot"],
      "country": "US",
      "tracked_at": "2024-03-10T06:00:00Z"
    }
  ],
  "meta": { "total": 143, "limit": 20, "offset": 0, "days": 7 }
}

Prompts are the questions your brand is tracked against across AI platforms. Each workspace has its own set of prompts.

List all prompts for a workspace.

Query parameters

Example

curl "https://www.linksii.com/api/v1/prompts?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer lnk_your_key"

Response

{
  "data": [
    {
      "id": "uuid",
      "workspace_id": "uuid",
      "prompt_text": "What is the best CRM for small businesses?",
      "category": "consideration",
      "tags": ["crm", "smb"],
      "is_active": true,
      "created_at": "2024-01-20T09:00:00Z"
    }
  ],
  "meta": { "total": 12, "limit": 20, "offset": 0 }
}

Create a new tracking prompt for a workspace.

Request body

Example

curl -X POST https://www.linksii.com/api/v1/prompts \
  -H "Authorization: Bearer lnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "prompt_text": "Which project management tools do remote teams prefer?",
    "category": "awareness",
    "tags": ["project-management", "remote"]
  }'

Competitors are brands whose AI visibility you want to compare against. They are tracked automatically alongside your brand during each tracking run.

List competitors for a workspace.

Query parameters

Example

curl "https://www.linksii.com/api/v1/competitors?workspace_id=WORKSPACE_ID" \
  -H "Authorization: Bearer lnk_your_key"

Response

{
  "data": [
    {
      "id": "uuid",
      "workspace_id": "uuid",
      "name": "Salesforce",
      "domain": "salesforce.com",
      "logo_url": "https://...",
      "created_at": "2024-01-22T11:00:00Z"
    }
  ],
  "meta": { "total": 4, "limit": 50, "offset": 0 }
}

Add a competitor to a workspace.

Request body

Analysis templates define the AI system prompt used when running visual analysis (see Analyze). Linksii ships with built-in templates; you can create custom ones too.

List built-in templates and your custom templates. Pass workspace_id to also include workspace-scoped templates.

Query parameters

Response

{
  "templates": [
    {
      "id": "uuid",
      "slug": "general",
      "name": "General Brand Analysis",
      "system_prompt": "Analyse the brand presence in this image...",
      "output_schema": { ... },
      "is_builtin": true,
      "workspace_id": null,
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ]
}

Create a custom analysis template. Slugs must be unique within your user + workspace scope.

Request body

Example

curl -X POST https://www.linksii.com/api/v1/templates \
  -H "Authorization: Bearer lnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Pricing Page Audit",
    "slug": "pricing_audit",
    "system_prompt": "Analyse this pricing page for clarity, trust signals, and conversion elements..."
  }'

Retrieve a single template by ID.

Update a custom template. Accepts the same fields as POST (all optional). Built-in templates cannot be modified.

Delete a custom template. Built-in templates cannot be deleted. Returns { "success": true }.

Manage API keys programmatically. Each workspace supports up to 10 active keys. The full key value is returned only once at creation — only the prefix is stored.

List active API keys for a workspace. Returns prefix only — the full key is never shown again after creation.

Query parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "key_prefix": "lnk_a1b2",
      "name": "Production",
      "last_used_at": "2024-03-10T08:00:00Z",
      "created_at": "2024-01-15T10:00:00Z",
      "revoked_at": null
    }
  ]
}

Create a new API key. The full key is returned in the key field and shown only once.

Request body

Response (201)

{
  "data": {
    "id": "uuid",
    "key": "lnk_a1b2c3d4e5f6...",   // shown ONCE — store securely
    "key_prefix": "lnk_a1b2",
    "name": "Production",
    "created_at": "2024-03-12T14:00:00Z",
    "workspace_id": "uuid"
  }
}

Revoke an API key by setting its revoked_at timestamp. Revoked keys immediately stop working.

Request body

Webhooks deliver real-time event notifications to your server. Each workspace supports up to 10 webhooks.

Supported events

Payload format

Linksii signs each delivery with an X-Linksii-Signature header (HMAC-SHA256 of the raw body using the webhook secret). Each request also carries a X-Linksii-Event header.

List webhooks for a workspace.

Query parameters

Response

{
  "data": [
    {
      "id": "uuid",
      "url": "https://your-server.com/webhooks/linksii",
      "events": ["tracking.completed"],
      "enabled": true,
      "created_at": "2024-03-01T10:00:00Z",
      "last_triggered_at": "2024-03-10T06:05:00Z",
      "last_status_code": 200
    }
  ]
}

Register a new webhook. The secret is returned once — use it to verify signature headers on incoming requests.

Request body

Example

curl -X POST https://www.linksii.com/api/v1/webhooks \
  -H "Authorization: Bearer lnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "url": "https://your-server.com/webhooks/linksii",
    "events": ["tracking.completed"]
  }'

Response (201)

{
  "data": {
    "id": "uuid",
    "url": "https://your-server.com/webhooks/linksii",
    "events": ["tracking.completed"],
    "enabled": true,
    "created_at": "2024-03-12T14:00:00Z",
    "secret": "a1b2c3d4..."   // shown ONCE — use to verify X-Linksii-Signature
  }
}

Delete a webhook. Pass id and workspace_id as query parameters.

Query parameters

The Analyze API runs AI-powered visual analysis on a URL or image, and can generate branded PDF reports or deliver them via email. It uses Claude vision under the hood.

Run visual analysis on a URL (screenshot captured automatically), image URL, or base64-encoded image. Results are stored and returned immediately.

Request body

Example

curl -X POST https://www.linksii.com/api/v1/analyze \
  -H "Authorization: Bearer lnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourcompany.com/pricing",
    "template": "general",
    "workspace_id": "WORKSPACE_ID"
  }'

Response

{
  "success": true,
  "analysis_id": "uuid",
  "template": "general",
  "model": "claude-sonnet-4-6",
  "result": { ... },   // template-specific JSON output
  "meta": {
    "image_source": "https://yourcompany.com/pricing",
    "created_at": "2024-03-12T14:00:00Z",
    "daily_quota": {
      "limit": 500,
      "used": 12,
      "remaining": 488
    }
  }
}

Run a full brand tracking pipeline across AI platforms and return a branded PDF report (base64) plus raw results. This runs Claude, ChatGPT, Gemini, and Perplexity in parallel.

Request body

Example

curl -X POST https://www.linksii.com/api/v1/analyze/report \
  -H "Authorization: Bearer lnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "analysis": {
      "workspace_id": "WORKSPACE_ID",
      "prompt_text": "What CRM do fast-growing startups recommend?",
      "platforms": ["claude", "chatgpt"],
      "country": "US"
    },
    "branding": {
      "company_name": "Acme Corp",
      "brand_color": "#2563eb"
    }
  }'

Response

{
  "success": true,
  "analysis_id": "uuid",
  "summary": {
    "brand_name": "Acme Corp",
    "platforms_analyzed": ["claude", "chatgpt"],
    "total_results": 2,
    "brand_mentioned_count": 2,
    "avg_visibility_pct": 78.5,
    "avg_sentiment": 71.2,
    "mention_rate_pct": 100,
    "brand_score": 74
  },
  "results": [...],   // full tracking results array
  "pdf": {
    "base64": "JVBERi0xLjQK...",
    "content_type": "application/pdf",
    "filename": "linksii-analysis-uuid.pdf",
    "url": "https://...",   // storage URL if configured
    "generated_at": "2024-03-12T14:01:30Z"
  }
}

Same as /analyze/report but also emails the PDF report to a recipient. Useful for automated white-label reporting workflows.

Additional request fields (vs /report)

Response differences

Same as /report but the top-level pdf key is replaced by a delivery key:

"delivery": {
  "recipient_email": "[email protected]",
  "email_sent": true,
  "pdf_url": "https://...",
  "delivered_at": "2024-03-12T14:01:45Z"
}

Given a domain, generate a curated set of tracking prompts and likely competitors. Powered by Gemini. Designed to turn audit generation into a one-input flow.

Scrapes the domain homepage for title and meta description, then uses AI to generate contextual prompts and competitors.

Request body

Example

curl -X POST https://www.linksii.com/api/v1/suggest \
  -H "Authorization: Bearer lnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "exampleclinic.com",
    "country": "GB",
    "prompt_count": 15,
    "competitor_count": 5
  }'

Response

{
  "success": true,
  "domain": "exampleclinic.com",
  "brand_name": "Example Aesthetics",
  "description": "Premium aesthetic clinic in London...",
  "country": "GB",
  "prompts": [
    {
      "prompt_text": "What are the best aesthetic clinics in London for lip filler?",
      "category": "consideration",
      "tags": ["aesthetic", "filler", "london"],
      "rationale": "High-intent treatment query in primary market"
    }
  ],
  "competitors": [
    {
      "name": "Competitor Clinic",
      "domain": "competitorclinic.com",
      "rationale": "Geographic and treatment-mix overlap"
    }
  ]
}

The Audit API is the headline pipeline: run many prompts across many platforms, compare against competitors, generate findings with prescriptive recommendations, and return a branded PDF report.

Run a complete audit. Returns aggregated data, findings, recommendations, and (optionally) a branded PDF as base64.

Request body

Example

curl -X POST https://www.linksii.com/api/v1/audit \
  -H "Authorization: Bearer lnk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": "WORKSPACE_ID",
    "prompts": [
      "What are the best aesthetic clinics in London?",
      "Who offers the best lip filler treatments in the UK?"
    ],
    "competitors": [
      { "name": "Competitor A", "domain": "competitora.com" }
    ],
    "country": "GB",
    "branding": {
      "company_name": "Orbyt",
      "brand_color": "#00FF6A",
      "logo_url": "https://orbythub.com/logo.png",
      "report_title": "AI Visibility Audit"
    }
  }'

Response

{
  "success": true,
  "audit_id": "uuid",
  "workspace_id": "uuid",
  "summary": {
    "brand_name": "Example Aesthetics",
    "platforms_analyzed": ["claude", "chatgpt", "gemini", "perplexity"],
    "prompts_analyzed": 15,
    "total_runs": 60,
    "brand_score": 28,
    "brand_visibility_pct": 18.3,
    "brand_mention_rate_pct": 22.0,
    "avg_brand_position": 4.7,
    "avg_sentiment": 65.4,
    "competitors": [
      {
        "name": "Competitor A",
        "mention_rate_pct": 80.0,
        "visibility_pct": 64.2
      }
    ],
    "top_sources_cited": [
      { "domain": "reddit.com", "citation_count": 24, "pct_of_total": 18.2 }
    ],
    "platform_breakdown": [...],
    "category_breakdown": [...]
  },
  "findings": [
    {
      "id": "invisibility_gap",
      "severity": "high",
      "headline": "Invisible in 78% of buyer queries",
      "narrative": "Across 15 prompts and 4 platforms...",
      "supporting_data": {...},
      "recommendations": [
        {
          "priority": 1,
          "action": "Publish problem-framed content...",
          "rationale": "AI platforms favour content that...",
          "effort": "medium",
          "expected_impact": "high"
        }
      ]
    }
  ],
  "discovered_competitors": [
    {
      "name": "Cathedral Dermatology",
      "domain": "cathedraldermatology.com",
      "mention_count": 7,
      "rationale": "Directly listed as a Belfast dermatology competitor in 7 AI responses"
    }
  ],
  "pdf": {
    "base64": "JVBERi0xLjQK...",
    "url": "https://...",
    "content_type": "application/pdf",
    "filename": "audit-example-aesthetics-uuid.pdf",
    "generated_at": "2026-04-21T14:01:30Z"
  },
  "meta": {
    "started_at": "2026-04-21T14:00:00Z",
    "completed_at": "2026-04-21T14:01:30Z",
    "duration_seconds": 90,
    "daily_quota": { "limit": 500, "used": 60, "remaining": 440 }
  }
}

Retrieve a previously-run audit by ID. Useful for re-downloading the PDF, fetching findings programmatically, or pulling raw tracking data.

Query parameters

Example

curl "https://www.linksii.com/api/v1/audit/AUDIT_ID?include_pdf=true" \
  -H "Authorization: Bearer lnk_your_key"

The Looker Studio endpoint powers the Linksii Community Connector for Google Looker Studio. It returns tracking results in a flat, BI-optimised format with support for date ranges, platform filtering, and schema discovery.

Query parameters

Schema mode

# Fetch field schema (used by the Looker Studio connector)
curl "https://www.linksii.com/api/v1/looker-studio?schema=1" \
  -H "Authorization: Bearer lnk_your_key"

Data response

{
  "data": [
    {
      "id": "uuid",
      "tracked_at": "2024-03-10T06:00:00Z",
      "ai_platform": "chatgpt",
      "country": "US",
      "sentiment_label": "positive",
      "sentiment_score": 0.72,
      "brand_mentioned": true,
      "brand_visibility_pct": 85.5,
      "brand_position": 2,
      "brand_ordinal_position": 2,
      "brand_relative_position": 0.18,
      "brand_appearance_count": 3,
      "mention_type": "direct",
      "prompt_query": "What CRM do startups recommend?"
    }
  ],
  "meta": {
    "total": 1450,
    "limit": 500,
    "offset": 0,
    "workspace_id": "uuid",
    "brand_name": "Acme Corp",
    "date_from": "2023-12-10T00:00:00Z",
    "date_to": "2024-03-10T00:00:00Z"
  }
}