API Documentation

Authentication

All /api/v1/* endpoints require a valid API key passed as a Bearer token in the Authorization header.

Authorization: Bearer bl_live_your_api_key_here

API keys are created by admins through the API Keys dashboard. Keys start with bl_live_ and are shown only once at creation — store them securely.

Error Responses

Submit an Audit

Submits a website URL for auditing. Returns immediately with the audit ID and a pending status. The audit runs asynchronously in the background (typically 30–50 seconds).

Request Body (JSON)

Example Request

curl -X POST https://brainylion.com/api/v1/audits \
  -H "Authorization: Bearer bl_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example-restoration.com",
    "audit_type": "basic",
    "callback_url": "https://your-server.com/webhook"
  }'

Response 201 Created

{
  "id": 1623,
  "status": "pending",
  "website": "https://example-restoration.com",
  "audit_type": "basic",
  "callback_url": "https://your-server.com/webhook",
  "created_at": "2026-03-25T18:23:05.000Z"
}

Get Audit Status & Results

Retrieve the status and results of a specific audit. Poll this endpoint until status is completed or failed.

Query Parameters

Status Values

Example Request

curl https://brainylion.com/api/v1/audits/1623 \
  -H "Authorization: Bearer bl_live_your_key"

Response (Completed)

{
  "id": 1623,
  "status": "completed",
  "website": "https://example-restoration.com",
  "audit_type": "basic",
  "overall_grade": "B",
  "runtime_ms": 34200,
  "created_at": "2026-03-25T18:23:05.000Z",
  "error_message": null,
  "scores": [
    {
      "question": "Is there a clearly visible phone number in the header?",
      "score": 1,
      "reason": "A phone number (555-123-4567) is prominently displayed in the top navigation bar."
    },
    {
      "question": "Does the website have a clear call-to-action above the fold?",
      "score": 0,
      "reason": "No clear CTA button is visible in the initial viewport. The first CTA appears below the fold."
    }
  ],
  "technical_seo_scores": [
    {
      "metric": "https",
      "passed": true,
      "value": "true",
      "recommendation": "Your site uses HTTPS. Great for security and SEO."
    },
    {
      "metric": "page_speed",
      "passed": true,
      "value": "1.2",
      "recommendation": "Excellent! Your page loads in 1.2 seconds."
    },
    {
      "metric": "title_tag",
      "passed": true,
      "value": "Example Restoration - Water Damage Experts",
      "recommendation": "Good! Your title tag is present and has appropriate length."
    }
  ]
}

List Your Audits

Returns a paginated list of all audits submitted with your API key.

Query Parameters

Example Request

curl "https://brainylion.com/api/v1/audits?status=completed&limit=5" \
  -H "Authorization: Bearer bl_live_your_key"

Response

{
  "audits": [
    {
      "id": 1623,
      "website": "https://example-restoration.com",
      "status": "completed",
      "audit_type": "basic",
      "overall_grade": "B",
      "runtime": 34200,
      "created_at": "2026-03-25T18:23:05.000Z",
      "error_message": null
    }
  ],
  "pagination": {
    "total": 42,
    "limit": 5,
    "offset": 0,
    "has_more": true
  }
}

Webhooks

When you provide a callback_url in your audit submission, we'll POST the results to that URL when the audit completes (or fails).

Delivery Details

• Method: POST
• Content-Type: application/json
• Retries: 3 attempts with exponential backoff (1s, 4s, 16s)
• Timeout: 10 seconds per attempt
• 4xx responses are not retried (considered permanent failures)

Headers

Webhook Payload

{
  "event": "audit.completed",
  "audit": {
    "id": 1623,
    "status": "completed",
    "website": "https://example-restoration.com",
    "audit_type": "basic",
    "overall_grade": "B",
    "runtime_ms": 34200,
    "created_at": "2026-03-25T18:23:05.000Z",
    "error_message": null,
    "scores": [ ... ],
    "technical_seo_scores": [ ... ]
  }
}

Recommended Polling Pattern

If not using webhooks, poll GET /api/v1/audits/:id with increasing intervals:

# Pseudocode for polling
response = POST /api/v1/audits { url: "https://example.com" }
audit_id = response.id

loop:
  wait 5 seconds
  result = GET /api/v1/audits/{audit_id}

  if result.status == "completed":
    # Use result.scores, result.overall_grade, etc.
    break

  if result.status == "failed":
    # Check result.error_message
    break

  # Still pending/processing — keep polling
  # Increase wait to 10s after first few attempts

Typical audit time is 30–50 seconds. We recommend starting with 5-second polling intervals and backing off to 10 seconds after 30 seconds.

Audit Types

Grading Scale

Each question is scored 0 (fail) or 1 (pass). The overall grade is calculated from the percentage of questions passed:

Rate Limits & Concurrency

The API processes up to 3 audits concurrently. Additional requests are queued and processed in order. Each audit requires a Puppeteer browser instance and an OpenAI API call, so this limit protects upstream service availability.

There are no per-key rate limits at this time, but excessive usage may be throttled.

Error Reference