AI Modules Features Steps Pricing FAQ Blog Tutorial Videos Glossary About Us Agencies
REST API v1

REST API Integration Guide

Connect your applications to AILabsAudit via the REST API. Retrieve audits, clients, reports and analytics programmatically.

Table of contents

  1. Prerequisites
  2. Get your API key
  3. Authentication
  4. First request
  5. Endpoints
  6. Pagination & filters
  7. Errors & rate limiting
  8. Code examples

Prerequisites

Before integrating the REST API, make sure you have:

1

An Enterprise or Partner account

API access requires an Enterprise plan or partner status. Request access if you don't have one yet.

2

A REST API key

You'll need an API key (format aila_...) generated from the API & Integrations page.

3

An HTTP client

Any HTTP client works: curl, Python requests, JavaScript fetch, Postman, etc.

Get your API key

Your API key is the same one used for MCP connections. If you already have one, you can use it directly.

1

Go to API & Integrations

Navigate to Account → API & Integrations in your dashboard.

2

Create a new key

Click "Create API Key", give it a name (e.g. "My App") and select the desired permissions.

3

Copy and store it safely

Your key starts with aila_. Copy it immediately — it won't be displayed again. Store it in an environment variable, never in your source code.

Tip

You can also explore the API interactively via our Swagger documentation which lists all available endpoints.

Authentication

The API supports two authentication methods. Choose the one that suits your stack:

Method 1: X-Api-Key header

CURL
curl -H "X-Api-Key: aila_your_key_here" \
     https://ailabsaudit.com/api/v1/clients

Method 2: Authorization Bearer

CURL
curl -H "Authorization: Bearer aila_your_key_here" \
     https://ailabsaudit.com/api/v1/clients

Security

Never expose your API key in client-side code (JavaScript in the browser). Always make API calls from your server (backend).

First request

Let's verify your connection works by fetching your client list:

CURL
curl -s -H "X-Api-Key: aila_your_key_here" \
     https://ailabsaudit.com/api/v1/clients | python3 -m json.tool

Successful response (200 OK)

JSON
{
    "success": true,
    "data": [
        {
            "id": 42,
            "name": "Acme Corp",
            "sector": "Technology",
            "website": "https://acme.com",
            "country": "FR",
            "created_at": "2025-01-15T10:30:00Z"
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 1,
        "total_pages": 1
    }
}

That's it!

If you see your client list, your API key is working. You can now explore all the available endpoints below.

Endpoints

The API is organized into 8 endpoint groups. All URLs are prefixed with https://ailabsaudit.com/api/v1/.

Clients

Method Endpoint Description
GET /clients List all clients
GET /clients/{id} Client detail
GET /clients/{id}/contacts Client contacts
GET /clients/{id}/competitors Client competitors
GET /clients/{id}/360 Complete 360 view

Audits

Method Endpoint Description
GET /audits List audits
GET /audits/{id} Audit detail
GET /audits/{id}/results Audit results
GET /audits/{id}/scores Visibility scores
POST /audits/launch Launch a new audit

Reports

Method Endpoint Description
GET /reports List reports
GET /reports/{id} Report detail
GET /reports/{id}/download Download PDF

Action Plans

Method Endpoint Description
GET /action-plans List action plans
GET /action-plans/{id} Plan detail
GET /action-plans/{id}/progress Plan progress

Questionnaires

Method Endpoint Description
GET /questionnaires List questionnaires
GET /questionnaires/{id}/responses Questionnaire responses

Analytics

Method Endpoint Description
GET /analytics/portfolio Portfolio overview
GET /analytics/leaderboard Visibility ranking
GET /analytics/scores/distribution Score distribution

Models

Method Endpoint Description
GET /models List available AI models
GET /models/{id} Model detail & pricing

Account

Method Endpoint Description
GET /account/profile Your profile
GET /account/credits Credit balance
GET /account/subscription Subscription info

Complete documentation

For the full list of endpoints, parameters and response schemas, see the interactive Swagger documentation.

Pagination & filters

All list endpoints support pagination via query parameters:

Parameter Default Description
page 1 Page number
per_page 20 Items per page (max 100)

Example with pagination

CURL
curl -H "X-Api-Key: aila_your_key_here" \
     "https://ailabsaudit.com/api/v1/audits?page=2&per_page=10"

Pagination object in response

JSON
{
    "pagination": {
        "page": 2,
        "per_page": 10,
        "total": 47,
        "total_pages": 5
    }
}

Errors & rate limiting

HTTP status codes

Code Meaning
200Success
400Bad request (invalid parameters)
401Unauthorized (missing or invalid API key)
403Forbidden (insufficient permissions)
404Not found
429Rate limited
500Server error

Error response format

JSON
{
    "success": false,
    "error": {
        "code": 401,
        "message": "Invalid or missing API key"
    }
}

Rate limiting

The API allows 60 requests per minute per API key. Response headers include rate limit information:

HTTP HEADERS
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709472000

If you hit the limit

When you receive a 429 response, wait until the X-RateLimit-Reset timestamp before retrying. Implement exponential backoff in your code for production use.

Code examples

Here are complete examples to get you started in your preferred language:

import requests

API_KEY = "aila_your_key_here"
BASE_URL = "https://ailabsaudit.com/api/v1"

headers = {"X-Api-Key": API_KEY}

# List clients
response = requests.get(f"{BASE_URL}/clients", headers=headers)
clients = response.json()

for client in clients["data"]:
    print(f"{client['name']} — {client['sector']}")

    # Get audits for each client
    audits = requests.get(
        f"{BASE_URL}/audits",
        headers=headers,
        params={"client_id": client["id"], "per_page": 5}
    ).json()

    for audit in audits["data"]:
        print(f"  Audit #{audit['id']} — Score: {audit.get('score', 'N/A')}")

# Download a report as PDF
report_id = 1
r = requests.get(
    f"{BASE_URL}/reports/{report_id}/download",
    headers=headers
)
if r.status_code == 200:
    with open(f"report_{report_id}.pdf", "wb") as f:
        f.write(r.content)
    print(f"Report saved: report_{report_id}.pdf")
const API_KEY = "aila_your_key_here";
const BASE_URL = "https://ailabsaudit.com/api/v1";

const headers = { "X-Api-Key": API_KEY };

// List clients
async function getClients() {
    const response = await fetch(`${BASE_URL}/clients`, { headers });
    const { data, pagination } = await response.json();

    console.log(`${pagination.total} clients found`);
    data.forEach(client => {
        console.log(`${client.name} — ${client.sector}`);
    });

    return data;
}

// Get audit results
async function getAuditResults(auditId) {
    const response = await fetch(
        `${BASE_URL}/audits/${auditId}/results`,
        { headers }
    );
    return await response.json();
}

// Paginate through all audits
async function getAllAudits() {
    let page = 1;
    let allAudits = [];

    while (true) {
        const response = await fetch(
            `${BASE_URL}/audits?page=${page}&per_page=50`,
            { headers }
        );
        const { data, pagination } = await response.json();
        allAudits.push(...data);

        if (page >= pagination.total_pages) break;
        page++;
    }

    return allAudits;
}

getClients().then(console.log);
<?php
$apiKey = "aila_your_key_here";
$baseUrl = "https://ailabsaudit.com/api/v1";

function apiRequest($endpoint, $params = []) {
    global $apiKey, $baseUrl;

    $url = $baseUrl . $endpoint;
    if (!empty($params)) {
        $url .= "?" . http_build_query($params);
    }

    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HTTPHEADER => ["X-Api-Key: $apiKey"],
    ]);

    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($httpCode !== 200) {
        throw new Exception("API error: HTTP $httpCode");
    }

    return json_decode($response, true);
}

// List clients
$clients = apiRequest("/clients");
foreach ($clients["data"] as $client) {
    echo "{$client['name']} — {$client['sector']}\n";
}

// Get audits with pagination
$audits = apiRequest("/audits", [
    "page" => 1,
    "per_page" => 10
]);
echo "Total audits: {$audits['pagination']['total']}\n";

// Get client 360 view
$client360 = apiRequest("/clients/42/360");
print_r($client360["data"]);

Ready to integrate the API?

Create your API key in 30 seconds and start building your integration.

Get started

Ready to audit your AI visibility?

Create your free account and receive 1000 bonus credits.

Create free account