BitBeamBitBeam
API Reference

BitBeam API

RESTful API for programmatic website audits, optimization reports, and monitoring. Build powerful integrations with BitBeam.

View Full DocumentationOpen Dashboard

Getting Started

Base URL

https://console.bitbeam.space/api

The Next.js website proxies requests to the dashboard API. The API uses JSON for request and response bodies.

Authentication

OAuth 2.0 with PKCE

Secure authentication for all API requests

BitBeam uses OAuth 2.0 with Keycloak for secure authentication. All API requests require a valid access token in the Authorization header.

Authorization: Bearer <access_token>
  • Tokens are obtained via the OAuth 2.0 authorization flow
  • Access tokens expire after 1 hour
  • Use refresh tokens to obtain new access tokens

API Endpoints

Website Audits

POST
/api/scan/start

Start a new website scan/audit

GET
/api/scan/{job_id}/status

Get audit progress and status

GET
/api/scan/{job_id}/results

Get full audit results and scores

Analysis & Reports

GET
/api/dashboard/metrics

Get system health score and recent activity

GET
/api/analysis/{analysis_id}

Get detailed page analysis by ID

GET
/api/reports

List generated reports for your tenant

AI Assistant

GET
/agi/{website_id}/{client_id}

SSE stream for real-time AI assistant chat

POST
/api/scan/knowledge

Ingest scanned website knowledge for AI assistant

GET
/health

API health check endpoint

Rate Limiting

API Rate Limits

To ensure fair usage and system stability, API requests are rate-limited based on your subscription tier.

Free Tier
100 requests/minute
Starter Tier
1,000 requests/minute
Pro Tier
10,000 requests/minute
Enterprise
Custom limits

Rate limit headers are included in all API responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Error Handling

Standard Error Responses

All API errors return a consistent JSON format with error details.

{
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided access token is invalid or expired",
    "details": "Token expired at 2024-01-15T10:30:00Z"
  }
}
400
Bad Request - Invalid request parameters
401
Unauthorized - Invalid or missing authentication
403
Forbidden - Insufficient permissions
429
Too Many Requests - Rate limit exceeded
500
Internal Server Error - Server error

Integration Options

Connect BitBeam to your workflows with REST, webhooks, or the embedded AI assistant widget.

REST API

Call the dashboard API directly with any HTTP client. Ideal for CI/CD pipelines and custom tooling.

curl /api/scan/start

AI Assistant Widget

Embed the JavaScript chat widget on your website to give visitors AI-powered answers based on your scanned content.

<script src="/bitbeam-assistant.js">

Webhooks

Receive audit completion and alert notifications at your own endpoints.

POST /webhooks/audits