Skip to main content

​
Overview

The /generate endpoint analyzes a repository and automatically generates an AGENTS.md file that describes its agent-usable capabilities, endpoints, and authentication requirements. It leverages AI providers (Gemini, Claude, OpenAI, or Beacon Cloud) to infer the repository’s functionality.

​
Endpoint

POST /generate

​
Rate Limiting

This endpoint is rate-limited to 20 requests per minute per IP address.

​
Authentication

No direct authentication is required for the API endpoint itself. However:
  • AI provider API keys (e.g., GEMINI_API_KEY, CLAUDE_API_KEY, OPENAI_API_KEY) must be configured as environment variables on the server
  • When using the beacon-ai-cloud provider, payment verification is required (see Payment Flow section)

​
Request

​
Request Body

The request body should be a JSON object containing repository context and configuration.
​
name
string
required
The name of the repository being analyzed.
​
readme
string
The contents of the repository’s README file, if available.
​
source_files
array
An array of source file objects containing the repository’s code.Each object should have:
  • path (string): File path relative to repository root
  • language (string): Programming language (e.g., “Rust”, “Python”, “TypeScript”)
  • content (string): The file’s source code content
​
openapi_spec
string
OpenAPI/Swagger specification content, if the repository has one.
​
package_manifest
string
Package manifest content (e.g., package.json, Cargo.toml, requirements.txt).
​
existing_agents_md
string
Content of an existing AGENTS.md file, if present. Used to preserve or enhance existing documentation.
​
provider
string
default:"gemini"
The AI provider to use for inference. Options:
  • "gemini" - Google’s Gemini (default)
  • "claude" - Anthropic’s Claude
  • "openai" - OpenAI’s GPT models
  • "beacon-ai-cloud" - Beacon’s hosted AI service (requires payment)

​
Example Request

curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-api-service",
    "readme": "# My API Service\n\nA REST API for...",
    "source_files": [
      {
        "path": "src/main.rs",
        "language": "Rust",
        "content": "fn main() { ... }"
      }
    ],
    "provider": "gemini"
  }'

​
Response

​
Success Response (200 OK)

​
success
boolean
required
Always true for successful requests.
​
agents_md
string
The complete generated AGENTS.md file content as a string.
​
manifest
object
Structured manifest object containing parsed capabilities and endpoints.Properties:
  • name (string): Repository name
  • description (string): Repository description
  • version (string): Version number
  • capabilities (array): List of agent-usable capabilities
  • endpoints (array): API endpoints with methods and parameters
  • authentication (object): Authentication requirements
  • rate_limits (object): Rate limiting information

​
Example Success Response

{
  "success": true,
  "agents_md": "# AGENTS.md — my-api-service\n\n> A REST API for...\n\n## Capabilities\n...",
  "manifest": {
    "name": "my-api-service",
    "description": "A REST API for managing resources",
    "version": "1.0.0",
    "capabilities": [
      {
        "name": "create_resource",
        "description": "Creates a new resource",
        "input_schema": { ... },
        "output_schema": { ... }
      }
    ],
    "endpoints": [
      {
        "path": "/api/resources",
        "method": "POST",
        "description": "Create a new resource"
      }
    ]
  }
}

​
Error Responses

​
402 Payment Required

Returned when using beacon-ai-cloud provider without valid payment. 
{
  "success": false,
  "error": "Payment required"
}
Response Headers:
  • x-payment-run-id: Unique run identifier for this generation request
  • x-payment-amount: Amount required in USDC (e.g., “0.09”)
  • x-payment-currency: Always “USDC”
  • x-payment-address-base: Base blockchain wallet address
  • x-payment-address-solana: Solana blockchain wallet address

​
409 Conflict

Returned when a transaction hash has already been used. 
{
  "success": false,
  "error": "Transaction hash already used"
}

​
429 Too Many Requests

Returned when rate limit is exceeded (>20 requests/minute).

​
500 Internal Server Error

Returned when generation fails. 
{
  "success": false,
  "error": "Inference failed: <error details>"
}

​
Payment Flow (beacon-ai-cloud)

When using the beacon-ai-cloud provider, a two-step payment flow is required:

​
Step 1: Initial Request (No Payment)

Send a generate request with provider: "beacon-ai-cloud" but no payment headers. The API returns a 402 Payment Required response with payment details in headers.

​
Step 2: Submit Payment

Send USDC to one of the provided wallet addresses:
  • Base blockchain: Use address from x-payment-address-base header
  • Solana blockchain: Use address from x-payment-address-solana header
Amount: Value from x-payment-amount header (typically 0.09 USDC)

​
Step 3: Retry with Payment Proof

Resend the same request with payment verification headers: 
curl -X POST http://localhost:8080/generate \
  -H "Content-Type: application/json" \
  -H "x-payment-txn-hash: <your_transaction_hash>" \
  -H "x-payment-chain: base" \
  -H "x-payment-run-id: <run_id_from_step1>" \
  -d '{ ... same request body ... }'
Payment Headers:
  • x-payment-txn-hash: Transaction hash from your USDC payment
  • x-payment-chain: Blockchain used ("base" or "solana")
  • x-payment-run-id: Run ID from the initial 402 response
The server will:
  1. Verify the payment on-chain
  2. Check that the transaction hasn’t been used before
  3. Process the generation request
  4. Mark the run as complete

​
Implementation Details

The endpoint (defined in src/main.rs:204-297):
  1. Validates the provider and handles payment flow for beacon-ai-cloud
  2. Calls inferrer::infer_capabilities() to analyze the repository using the specified AI provider
  3. Generates the AGENTS.md file using generator::generate_agents_md()
  4. Returns both the raw markdown content and structured manifest
For beacon-ai-cloud with successful payment, the run is marked complete in the database with the generated content.

Build docs developers (and LLMs) love

Get started for freeTalk to us