ApiLot

Autonomous API documentation agent for backend projects.

ApiLot scans your source code, detects endpoint changes, updates Postman documentation, and stores API change history in Neo4j.

Features

• Realtime sync with watch and one-shot sync with sync.
• Route extraction for Go/Node/Python files.
• AI extractor provider switch via env (openai or pioneer).
• Breaking-change classification with OpenAI.
• Postman collection auto-creation and route-level update flow.
• Neo4j history timeline for API changes.
• Pending sync queue + retry behavior for transient Postman errors.
• Optional debug mode for detailed AI/process logs.

Requirements

• Go 1.23.2+
• A Postman API key
• (Optional but recommended) Neo4j instance credentials
• AI API key for your selected extractor provider:
  • OpenAI (OPENAI_API_KEY), or
  • Pioneer (PIONEER_API_KEY)

Installation

Option A: Run directly

go run ./cmd/apilot help

Option B: Build binary

go build -o apilot ./cmd/apilot
./apilot help

Quick Start

1. Create a .env in repo root.
2. Set minimum required keys:
   • POSTMAN_API_KEY
   • AI key for your provider (OPENAI_API_KEY or PIONEER_API_KEY)
   • WATCH_DIR (project to scan)
3. Initialize:

apilot init

4. Choose your workflow:
   • Realtime:

     apilot watch

   • One-shot:

     apilot sync

Supported Inputs

Source file types watched/scanned

• .go
• .js
• .ts
• .py

Framework coverage (current)

• Go: Gin-focused deterministic extraction (route groups supported)
• Node: Express patterns
• Python: FastAPI / Django patterns

Deterministic parsers run first. AI extraction is used as fallback/enrichment based on config and route detection heuristics.

Configuration (.env)

Use these keys in your .env:

Core

• WATCH_DIR
  Directory to scan/watch (default .).

• POSTMAN_API_KEY
  Required for Postman sync.

• POSTMAN_WORKSPACE_NAME
  Optional. If empty, init prompts workspace selection interactively.

AI extractor provider switch

• AI_EXTRACTOR_PROVIDER=openai|pioneer
  Switches extractor backend without code changes.

OpenAI extractor keys

• OPENAI_API_KEY
• OPENAI_EXTRACT_ENDPOINT (default https://api.openai.com/v1/responses)
• OPENAI_EXTRACT_MODEL (default gpt-4.1-mini)

Pioneer extractor keys

• PIONEER_API_KEY
• PIONEER_ENDPOINT (default https://api.pioneer.ai/inference)
• PIONEER_MODEL (default base:Qwen/Qwen3-32B)
• PIONEER_TASK (default generate)

Lifecycle docs generation

• DOC_MODE=deep|off
deep generates endpoint lifecycle docs and attaches them to endpoint descriptions.

• DOC_AI_MODEL
  Model used for lifecycle documentation generation.

Classification

• OPENAI_API_KEY is also used for breaking-change classification.

Neo4j

• NEO4J_URI
• NEO4J_USER
• NEO4J_PASSWORD

If Neo4j config is missing, graph history persistence is skipped.

Debug

• DEBUG=true|false
  When true, prints detailed AI/process logs, including request/response debug traces.

Commands

• apilot init
  Bootstrap local state + Postman collection from current codebase.

• apilot watch
  Realtime loop for file changes, diffing, classification, Postman sync, and Neo4j writes.

• apilot sync
  One-time full rescan + sync (useful when not running watch).

• apilot diff
  Show pending unsynced changes from .apilot/pending.json.

• apilot history
  Show API change timeline from Neo4j in terminal table format.

• apilot help
  Detailed command guide.

Local State Files

ApiLot stores runtime state under .apilot/:

• .apilot/state.json
  Postman sync state (workspace, collection, route sync metadata).

• .apilot/routes_state.json
  Last known extracted route map.

• .apilot/pending.json
  Pending change sets when sync fails and needs retry.

Recommended Workflows

Workflow A: Realtime

apilot init
apilot watch

Workflow B: End-of-session sync

apilot init
# ... code normally ...
apilot sync

Notes & Troubleshooting

• If Postman rate limit errors occur, ApiLot retries with backoff.
• If init sees existing state, it prompts before cleanup/re-init.
• If history shows empty project values for very old records, newer syncs will persist project name.
• If AI extraction appears noisy during development, set DEBUG=false.