Skip to main content

​
Introduction

The Beacon REST API provides programmatic access to Beacon’s core functionality for generating and validating AGENTS.md files. The API allows you to integrate Beacon’s repository analysis and agent capability inference into your own workflows, services, and automation pipelines.

​
API vs CLI

​
When to Use the API

The REST API is ideal when you need to:
  • Integrate Beacon into existing web services or applications
  • Build automation pipelines that generate AGENTS.md files on demand
  • Create custom user interfaces or dashboards
  • Process multiple repositories programmatically
  • Integrate with CI/CD systems via HTTP requests

​
When to Use the CLI

The CLI is better suited for:
  • Local development and testing
  • One-off repository analysis
  • Manual validation of AGENTS.md files
  • Simple scripts and shell automation
  • Quick prototyping and experimentation

​
Base URL

When running the Beacon server locally: 
http://localhost:8080
For Beacon Cloud (hosted service): 
https://api.beacon.cloud
Start the local server using: 
beacon serve --port 8080

​
Response Format

All API responses are returned in JSON format with a consistent structure:

​
Success Response

{
  "success": true,
  "agents_md": "...",
  "manifest": { ... }
}

​
Error Response

{
  "success": false,
  "error": "Error message describing what went wrong"
}

​
Rate Limits

The Beacon API implements rate limiting to ensure fair usage and system stability:
Rate Limit: 20 requests per minute per IP address
Rate limits apply to:
  • POST /generate
  • POST /validate
Rate limits do NOT apply to:
  • GET /health
When you exceed the rate limit, the API returns: 
HTTP/1.1 429 Too Many Requests
The rate limit window is 60 seconds. After the window expires, your request count resets.

​
Error Codes

The Beacon API uses standard HTTP status codes:
Status CodeMeaningDescription
200OKRequest succeeded
400Bad RequestInvalid request body or parameters
402Payment RequiredPayment needed for Beacon Cloud
409ConflictTransaction hash already used
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer-side error occurred

​
Common Error Scenarios

The request body is malformed or missing required fields.
{
  "success": false,
  "error": "Scanning failed: Invalid repository path"
}
Using Beacon Cloud requires payment. See the authentication documentation for payment headers.
{
  "success": false,
  "error": "Payment required"
}
Response includes payment details in headers:
  • x-payment-run-id
  • x-payment-amount
  • x-payment-currency
  • x-payment-address-base
  • x-payment-address-solana
You’ve exceeded the rate limit of 20 requests per minute.Wait 60 seconds before retrying or implement exponential backoff in your client.
An error occurred during inference or file generation.
{
  "success": false,
  "error": "Inference failed: AI provider timeout"
}

​
Getting Started

Here’s a quick example to get you started with the Beacon API: 
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-project",
    "readme": "# My Project\nA sample application",
    "source_files": [
      {
        "path": "main.rs",
        "language": "Rust",
        "content": "fn main() { println!(\"Hello\"); }"
      }
    ],
    "provider": "gemini"
  }'

​
Next Steps

Authentication

Learn about AI provider keys and Beacon Cloud payment

Generate Endpoint

Generate AGENTS.md files programmatically

Validate Endpoint

Validate AGENTS.md file content

Health Check

Monitor server health and status

Build docs developers (and LLMs) love

Get started for freeTalk to us