API v1

API Documentation

Integrate Beconova into your application with our powerful REST API. Simple integration with standard HTTP requests.

REST API Quick Start

Integrate Beconova with simple fetch() calls. No additional packages needed — just use the REST API with your API key.

Quick Start

JavaScript / REST API

const API_KEY = 'lum_xxxxxxxxxxxxx';
const BASE_URL = 'https://api.beconova.de';

const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json',
};

// List your stores
const stores = await fetch(`${BASE_URL}/api/stores`, { headers })
  .then(res => res.json());

// Get visibility status
const status = await fetch(`${BASE_URL}/api/visibility-addon/status`, { headers })
  .then(res => res.json());
console.log(`AI Visibility Score: ${status.latestScore}`);

// List tracked keywords
const keywords = await fetch(`${BASE_URL}/api/visibility-addon/keywords`, { headers })
  .then(res => res.json());

Quick Start

Create API Key

Send Request

Send your first API requests with your API key.

Integrate Data

Integrate the API responses into your application.

Authentication

All API requests require a valid API key in the Authorization header.

header

X-API-Key: lum_xxxxxxxxxxxxx

Security Note: Never share your API key publicly. Use environment variables for secure storage.

Endpoints

Method	Endpoint	Description	Auth
GET	/api/stores	List all stores	Required
GET	/api/products	Retrieve list of all products	Required
POST	/api/products	Create a new product	Required
PUT	/api/products/:id	Update a product	Required
DELETE	/api/products/:id	Delete a product	Required
GET	/api/services	Retrieve list of all services	Required
POST	/api/validate	Perform schema validation	Required
GET	/api/visibility-addon/status	AI Visibility Status & Score	Required
GET	/api/visibility-addon/keywords	List tracked keywords	Required
POST	/api/stores/:storeId/scan	Trigger website scan	Required
GET	/api/stores/:storeId/scan-results	Retrieve scan results	Required
GET	/api/visibility-addon/citations	List AI citations	Required
GET	/api/visibility-addon/competitors	Get competitors & rankings	Required
GET	/api/gsc/analytics	Google Search Console data	Required
GET	/api/content/recommendations	Get content recommendations	Required
GET	/api/sentiment/overview	Sentiment analysis overview	Required

Rate Limits

Global1.000 req/15 min

Auth50 req/15 min

Visibility30 req/min

Publisher / Feeds90 req/min

Webhooks100 req/min

Rate limit information is returned in response headers: RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset.

Interactive API Documentation

Test all endpoints directly in the interactive Swagger UI. All 50+ endpoints with schemas, examples, and try-it-out functionality.

Open Swagger UI

Code Examples

cURL

# List all products
curl -X GET "https://api.beconova.de/api/products?storeId=YOUR_STORE_ID" \
  -H "X-API-Key: lum_xxxxxxxxxxxxx"

# Start a website scan
curl -X POST "https://api.beconova.de/api/stores/YOUR_STORE_ID/scan" \
  -H "X-API-Key: lum_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"fullCrawl": true}'

# Get visibility score
curl -X GET "https://api.beconova.de/api/visibility-addon/status" \
  -H "X-API-Key: lum_xxxxxxxxxxxxx"

JavaScript / REST API

const API_KEY = 'lum_xxxxxxxxxxxxx';
const BASE_URL = 'https://api.beconova.de';
const headers = {
  'X-API-Key': API_KEY,
  'Content-Type': 'application/json',
};

// List products
const products = await fetch(
  `${BASE_URL}/api/products?storeId=YOUR_STORE_ID`,
  { headers }
).then(res => res.json());

// Create a product
await fetch(`${BASE_URL}/api/products`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    storeId: 'YOUR_STORE_ID',
    title: 'Premium Coffee Maker',
    brand: 'BrewMaster',
    category: 'Kitchen Appliances',
  }),
});

// Start a scan
await fetch(`${BASE_URL}/api/stores/YOUR_STORE_ID/scan`, {
  method: 'POST',
  headers,
  body: JSON.stringify({ fullCrawl: true }),
});

// Error handling
const res = await fetch(`${BASE_URL}/api/stores/YOUR_STORE_ID`, { headers });
if (res.status === 429) {
  const retryAfter = res.headers.get('Retry-After');
  console.log(`Rate limited. Retry after ${retryAfter}s`);
}

Python

import requests

API_KEY = 'lum_xxxxxxxxxxxxx'
BASE_URL = 'https://api.beconova.de'
headers = {'X-API-Key': API_KEY}

# List stores
stores = requests.get(f'{BASE_URL}/api/stores', headers=headers).json()

# Get visibility status
status = requests.get(f'{BASE_URL}/api/visibility-addon/status', headers=headers).json()
print(f"Score: {status['latestScore']}")

# Add a keyword to track
requests.post(
    f'{BASE_URL}/api/visibility-addon/keywords',
    headers={**headers, 'Content-Type': 'application/json'},
    json={'keyword': 'best coffee maker'}
)

Need Help?

Our developer support will help you with the integration.

Contact Support

Method

Endpoint

Description

Auth

GET

/api/stores

List all stores

Required

GET

/api/products

Retrieve list of all products

Required

POST

/api/products

Create a new product

Required

PUT

/api/products/:id

Update a product

Required

DELETE

/api/products/:id

Delete a product

Required

GET

/api/services

Retrieve list of all services

Required

POST

/api/validate

Perform schema validation

Required

GET

/api/visibility-addon/status

AI Visibility Status & Score

Required

GET

/api/visibility-addon/keywords

List tracked keywords

Required

POST

/api/stores/:storeId/scan

Trigger website scan

Required

GET

/api/stores/:storeId/scan-results

Retrieve scan results

Required

GET

/api/visibility-addon/citations

List AI citations

Required

GET

/api/visibility-addon/competitors

Get competitors & rankings

Required

GET

/api/gsc/analytics

Google Search Console data

Required

GET

/api/content/recommendations

Get content recommendations

Required

GET

/api/sentiment/overview

Sentiment analysis overview

Required

# List all products curl -X GET "https://api.beconova.de/api/products?storeId=YOUR_STORE_ID" \ -H "X-API-Key: lum_xxxxxxxxxxxxx" # Start a website scan curl -X POST "https://api.beconova.de/api/stores/YOUR_STORE_ID/scan" \ -H "X-API-Key: lum_xxxxxxxxxxxxx" \ -H "Content-Type: application/json" \ -d '{"fullCrawl": true}' # Get visibility score curl -X GET "https://api.beconova.de/api/visibility-addon/status" \ -H "X-API-Key: lum_xxxxxxxxxxxxx"

import requests API_KEY = 'lum_xxxxxxxxxxxxx' BASE_URL = 'https://api.beconova.de' headers = {'X-API-Key': API_KEY} # List stores stores = requests.get(f'{BASE_URL}/api/stores', headers=headers).json() # Get visibility status status = requests.get(f'{BASE_URL}/api/visibility-addon/status', headers=headers).json() print(f"Score: {status['latestScore']}") # Add a keyword to track requests.post( f'{BASE_URL}/api/visibility-addon/keywords', headers={**headers, 'Content-Type': 'application/json'}, json={'keyword': 'best coffee maker'} )