Overview This API server provides HTTP endpoints for N8N workflows to interact with Airbais tools asynchronously. It supports job management, status tracking, and result retrieval for long-running analysis tasks.
Installation
Navigate to automation directory
bash cd automation
Install dependencies
bash pip install -r requirements.txt
Start the server
bash python api_server.py
The server will start on port 8888.
API Endpoints Health Check curl http://localhost:8888/health
Intent Crawler
GRASP Evaluator
GEO Evaluator
LLM Evaluator
Start Analysis POST http://localhost:8888/intentcrawler/analyze Content-Type: application/json { "url" : "https://example.com" }
IntentCrawler analyzes website content to discover user intents for LLM understanding.
Start Evaluation POST http://localhost:8888/graspevaluator/analyze Content-Type: application/json { "url" : "https://example.com", "verbose" : true }
GRASP Evaluator assesses content quality across five dimensions: Grounded, Readable, Accurate, Structured, Polished.
Start Evaluation POST http://localhost:8888/geoevaluator/analyze Content-Type: application/json { "url" : "https://example.com", "name" : "Example Site", "max_pages" : 50, "dashboard" : true }
GEO Evaluator performs Generative Engine Optimization analysis to improve LLM understanding.
Start Evaluation POST http://localhost:8888/llmevaluator/analyze Content-Type: application/json { "config" : "example_config.md", "log_level" : "INFO", "dry_run" : false }
LLM Evaluator requires a configuration file that defines brand information, evaluation prompts, and LLM settings. See the llmevaluator directory for example config files.
Common Endpoints
Check Status GET http://localhost:8888/status/{job_id} Response { "job_id" : "uuid-here" , "tool" : "intentcrawler" , "status" : "running|completed|failed" , "created_at" : "2024-01-01T10:00:00" , "updated_at" : "2024-01-01T10:01:00" , "completed_at" : null }
Get Results GET http://localhost:8888/results/{job_id} Response { "job_id" : "uuid-here" , "tool" : "intentcrawler" , "status" : "completed" , "results" : { "output_directory" : "/path/to/results/2024-01-01" , "files" : { "dashboard_data" : "/path/to/dashboard-data.json" , "intent_report" : "/path/to/intent-report.json" }, "metrics" : { "pages_analyzed" : 150 , "intents_discovered" : 12 } } } Common Issues
Trailing Characters in Job IDs
If you’re copying job IDs from terminal output, be careful not to include any
trailing characters like backticks or quotes. The API will automatically clean
common trailing special characters, but it’s best to copy only the UUID
itself.
If you get a “tool not found” error, check that: 1. The tool name is correct
in your endpoint URL 2. The API server has been restarted after configuration
changes 3. The tool is properly configured in tools_config.yaml
Test scripts are provided for each tool:
IntentCrawler
GRASP Evaluator
GEO Evaluator
LLM Evaluator
python test_api.py https://example.com
Configuration
Tool configurations are managed in tools_config.yaml. This file contains
tool definitions, server settings, and timeouts.
Edit Configuration
Update tools_config.yaml with your tool definition: your_tool_name : name : "Your Tool Display Name" module_path : "your_tool_folder" script : "your_tool.py" description : "What your tool does" result_files : - "dashboard-data.json" - "your-report.json" required_params : - "url" optional_params : - "config" - "output" param_style : "flags" # or "positional" or "config_file"
Restart Server
The API server will automatically pick up the new tool configuration on restart.
Parameter Styles flags
positional
config_file
Default style - All parameters use --flag formatpython tool.py --url https://example.com --verbose Used by: GRASP Evaluator, GEO Evaluator Positional arguments - URL as direct argument bash python tool.py https://example.com --config config.yaml Used by: IntentCrawler
Config file style - Configuration file as positional argumentpython tool.py config.md --log-level INFO Used by: LLM Evaluator Server Settings
Modify Server Configuration
Edit the server section in tools_config.yaml: server : port : 8888 host : "0.0.0.0" debug : false cors_enabled : true Start Analysis Response { "job_id" : "uuid-here" , "status" : "queued" , "message" : "Tool analysis started" } Status Response { "job_id" : "uuid-here" , "tool" : "toolname" , "status" : "running|completed|failed" , "created_at" : "2024-01-01T10:00:00" , "updated_at" : "2024-01-01T10:01:00" , "completed_at" : "2024-01-01T10:05:00" } Results Response { "job_id" : "uuid-here" , "tool" : "toolname" , "status" : "completed" , "results" : { "output_directory" : "/path/to/results" , "files" : { "dashboard_data" : "/path/to/dashboard-data.json" }, "metrics" : { "pages_analyzed" : 150 } } }
The automation API provides a consistent interface for all Airbais tools,
making it easy to integrate with N8N workflows and other automation platforms.
