API Documentation

Everything you need to integrate AI Presence Index into your workflow.

AI Presence Index provides two types of endpoints:

1. Public endpoints — serve your llms.txt, Schema.org JSON-LD, and widget script. No authentication required. Accessed via your API key or business slug.
2. Protected endpoints — manage your business data, view analytics, and configure settings. Require an authenticated session or API key header.

Authentication

Protected endpoints support two authentication methods:

Cookie Session (Browser)

When logged in via the web app, a secure HttpOnly cookie (aip_session) is set automatically. All requests from the browser include this cookie. State-changing requests (POST, PUT, DELETE) must also include a CSRF token.

# Get CSRF token first
curl https://aipresenceindex.com/api/v1/auth/csrf-token \
  -c cookies.txt

# Use it in state-changing requests
curl -X POST https://aipresenceindex.com/api/v1/business \
  -b cookies.txt \
  -H "X-CSRF-Token: <token-from-above>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Business"}'

API Key (Programmatic)

Your API key is provided after registration. Include it in the X-API-Key header for programmatic access.

curl https://aipresenceindex.com/api/v1/business \
  -H "X-API-Key: your_api_key_here"

Base URL

https://aipresenceindex.com

All endpoints below are relative to this base URL. Responses are JSON unless otherwise noted.

llms.txt

Retrieve your business information in llms.txt format, optimized for AI language models.

GET /v1/{apiKey}/llms.txt

Retrieve llms.txt using your API key.

curl https://aipresenceindex.com/v1/YOUR_API_KEY/llms.txt

GET /v1/business/{slug}/llms.txt

Retrieve llms.txt for a published business using its public slug.

curl https://aipresenceindex.com/v1/business/my-restaurant/llms.txt

Response: text/markdown

schema.json

Get Schema.org structured data in JSON-LD format, ready to embed in your website or feed to AI systems.

GET /v1/{apiKey}/schema.json

Retrieve Schema.org JSON-LD via API key. Response is cached for performance.

curl https://aipresenceindex.com/v1/YOUR_API_KEY/schema.json

GET /v1/business/{slug}/schema.json

Retrieve Schema.org JSON-LD for a published business via slug.

curl https://aipresenceindex.com/v1/business/my-restaurant/schema.json

Response: application/ld+json

inject.js (Smart Widget)

Embed a single script tag on your website to automatically add Schema.org markup and llms.txt link tags. Available on Pro plans and above.

GET /v1/{apiKey}/inject.js

Add this script to your website's <head>:

<script src="https://aipresenceindex.com/v1/YOUR_API_KEY/inject.js"
        async defer></script>

The widget will inject JSON-LD Schema.org and a <link rel="llms-txt"> tag automatically.

Auth Endpoints

POST /api/v1/auth/register

Create a new account. Returns API key on success.

curl -X POST https://aipresenceindex.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "password": "SecurePass123",
    "name": "Your Name"
  }'

POST /api/v1/auth/login

Log in. If email 2FA is enabled, returns a verification token. Otherwise sets session cookie.

POST /api/v1/auth/verify-code

Verify the 6-digit email code from 2FA. Sets session cookie on success.

POST /api/v1/auth/logout

End the current session. Requires auth.

GET /api/v1/auth/session

Check current session status and get user info.

GET /api/v1/auth/csrf-token

Get a CSRF token. Required for all POST/PUT/DELETE requests when using cookie auth.

Business Endpoints

All business endpoints require authentication.

GET /api/v1/business

Get your business profile with hours and services.

curl https://aipresenceindex.com/api/v1/business \
  -H "X-API-Key: YOUR_API_KEY"

POST /api/v1/business

Create your business profile.

curl -X POST https://aipresenceindex.com/api/v1/business \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Restaurant",
    "category": "restaurant",
    "description": "Fine Italian dining",
    "phone": "+39 06 1234567",
    "email": "info@myrestaurant.com",
    "website": "https://myrestaurant.com",
    "address": "Via Roma 1",
    "city": "Rome",
    "state": "RM",
    "zip_code": "00100",
    "country": "IT"
  }'

PUT /api/v1/business

Update business details. Send only the fields you want to change.

PUT /api/v1/business/hours

Update opening hours for each day of the week.

POST /api/v1/business/publish

Publish your business to the public directory. Makes it accessible via slug-based URLs.

GET /api/v1/business/services

POST /api/v1/business/services

PUT /api/v1/business/services/:id

DELETE /api/v1/business/services/:id

CRUD operations for business services (e.g., menu items, offerings).

Analytics Endpoints

Track AI bot visits to your business data. All require authentication.

GET /api/v1/analytics/summary

Dashboard summary: total hits, AI visits, top bots, endpoint stats (last 30 days).

GET /api/v1/analytics/daily?days=30

Daily hit counts for chart visualization. Configurable time range.

GET /api/v1/analytics/bots?days=30

Breakdown by AI bot: visits, unique days, last visit.

GET /api/v1/analytics/geo?days=30

Geographic distribution by country (top 20).

GET /api/v1/analytics/hits?page=1&limit=50&ai_only=false

Paginated detailed hit log. Use ai_only=true to filter to AI bots only.

GET /api/v1/analytics/export?format=json&days=30

Export analytics data. Supports json and csv formats. Requires paid plan.

GET /api/v1/analytics/usage

Your current month API usage and plan limits.

Rate Limits

Plan	llms.txt / schema.json	API requests
Free	1,000/mo	100/mo
Pro	10,000/mo	1,000/mo
Business	100,000/mo	10,000/mo
Enterprise	1,000,000/mo	100,000/mo

Auth-specific rate limits: login 5 req/min, register 3 req/min. Exceeding limits returns HTTP 429.

Error Responses

All errors follow this format:

{
  "success": false,
  "error": "Human-readable error message"
}

Code	Meaning
400	Bad request — invalid or missing parameters
401	Unauthorized — missing or invalid credentials
403	Forbidden — valid auth but insufficient plan or permissions
404	Not found — resource does not exist
409	Conflict — resource already exists (e.g., duplicate email)
429	Too many requests — rate limit exceeded
500	Internal server error