API Reference

The AiVIS API lets you programmatically access your scan results, business data, and account information. Available on the Agency plan.

Introduction

The AiVIS REST API returns JSON responses. The base URL for all endpoints is:

https://getaivis.ai/api/v1

Generate API keys from your Account Settings page. Each Agency account can have up to 5 active API keys.

Authentication

Pass your API key as a Bearer token in the Authorization header of every request.

curl https://getaivis.ai/api/v1/me \
  -H "Authorization: Bearer aivis_your_key_here"

API keys start with aivis_. Store them securely — they are shown only once when generated.

Errors

The API uses standard HTTP status codes. Error responses include an error field with a description.

{ "error": "Invalid API key" }

Status	Meaning
200	Success
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid API key
403	Forbidden — Agency plan required
404	Resource not found
500	Server error

Account

GET /api/v1/me Get account info

Returns the authenticated user's account details.

{
  "user": {
    "id": "uuid",
    "email": "you@company.com",
    "name": "Jane Smith",
    "plan": "agency",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

Businesses

GET /api/v1/businesses List all businesses

Returns all businesses associated with your account, including scan counts and latest authority scores.

{
  "businesses": [
    {
      "id": "uuid",
      "name": "Acme Corp",
      "website": "https://acme.com",
      "industry": "SaaS",
      "geography": "United States",
      "scan_count": 4,
      "latest_authority": 72,
      "created_at": "2025-01-15T10:00:00Z"
    }
  ]
}

Scans

GET /api/v1/scans List scans

Returns completed scans. Filter by business with ?business_id=.

Parameter	Type	Description
business_id	string	optional Filter by business UUID
limit	integer	optional Max results (default 20, max 100)
offset	integer	optional Pagination offset

curl "https://getaivis.ai/api/v1/scans?business_id=uuid&limit=5" \
  -H "Authorization: Bearer aivis_your_key_here"

GET /api/v1/scans/:id Get full scan detail

Returns complete scan data including all query results, narrative breakdown, strategic commentary, and content calendar.

{
  "scan": {
    "id": "uuid",
    "business_name": "Acme Corp",
    "status": "complete",
    "authority_score": 72,
    "commercial_score": 68,
    "displacement_rate": 34.5,
    "narrative_counts": { "OWNED": 18, "WEAK": 9, "CONTESTED": 8, "LOST": 12, "WHITE_SPACE": 3 },
    "results": [...],
    "commentary": "Strategic analysis...",
    "calendar": "Week 1: ...",
    "completed_at": "2025-03-15T14:30:00Z"
  }
}