# Boltwork API

## What this service does
Boltwork is an autonomous agent-native AI services API. Agents discover,
pay, and use services autonomously over Bitcoin Lightning — no accounts,
no API keys, no subscriptions.

### PDF Summarisation
Accepts a PDF document and returns a structured JSON summary.
Useful for: research papers, reports, contracts, or any PDF.

### Code Review
Accepts source code and returns a structured JSON review including bugs,
security issues, code quality observations, and recommended actions.
Supports: Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, C#,
Ruby, PHP, Swift, Kotlin, Scala, Shell, SQL, Terraform, and more.

### Web Page Summarisation
Accepts any web page URL and returns a structured JSON summary including
title, key points, topics, sentiment, and content type.

### Data Extraction
Accepts a PDF URL and extracts structured data including dates, parties,
amounts, line items, and reference numbers. Useful for invoices, contracts,
receipts, and forms.

### Translation
Accepts text directly or a PDF/web page URL and translates to any of 24
supported languages. Returns translated text with source language detection.

### Analysis
POST https://parsebit-lnd.fly.dev/analyse/tables   - Extract all tables from a PDF as structured JSON (JSON body: url, max_pages)
POST https://parsebit-lnd.fly.dev/analyse/compare  - Compare two PDFs (JSON body: url_a, url_b, max_pages)
POST https://parsebit-lnd.fly.dev/analyse/explain  - Explain code in plain English (JSON body: code or url, language?)

## Payment Protocol: L402 (Bitcoin Lightning Network)
- PDF Summarisation: 500 satoshis per call
- Code Review: 2000 satoshis per call
- Web Page Summarisation: 100 satoshis per call
- Data Extraction: 200 satoshis per call
- Translation: 150 satoshis per call
- Table Extraction: 300 satoshis per call
- Document Comparison: 500 satoshis per call
- Code Explanation: 500 satoshis per call
- Agent Memory Write: 10 satoshis per call
- Agent Memory Read: 5 satoshis per call
- Workflow Pipeline: 1000 satoshis per run
- Agent Suggest: free (no payment required)
- Trial endpoints: free (rate-limited, capped input)

No account, signup, or API key required. Any Lightning-capable agent
can use this service autonomously.

## Base URL
https://parsebit-lnd.fly.dev

## Endpoints

### Summarisation
POST https://parsebit-lnd.fly.dev/summarise/upload  - Upload a PDF file (multipart/form-data, field: file)
POST https://parsebit-lnd.fly.dev/summarise/url     - Summarise PDF from URL (JSON body: url, max_pages)

### Code Review
POST https://parsebit-lnd.fly.dev/review/code       - Review code as text (JSON body: code, language?, filename?)
POST https://parsebit-lnd.fly.dev/review/url        - Review code from URL (JSON body: url, language?)
                                       Supports GitHub/GitLab blob URLs (auto-converted to raw)

### Extraction & Translation
POST https://parsebit-lnd.fly.dev/extract/webpage   - Summarise any web page (JSON body: url)
POST https://parsebit-lnd.fly.dev/extract/data      - Extract structured data from PDF (JSON body: url, max_pages)
POST https://parsebit-lnd.fly.dev/translate         - Translate text or document (JSON body: text or url, target_language)

### Workflow (Pipeline Composition)
POST https://parsebit-lnd.fly.dev/workflow/run      - Chain services in a single call (JSON body: steps[], label?)
GET  https://parsebit-lnd.fly.dev/workflow/info     - Supported services and pipeline syntax (free)

### Agent Memory
POST https://parsebit-lnd.fly.dev/memory/store      - Write key-value pairs for your agent (JSON body: agent_id, entries{})
POST https://parsebit-lnd.fly.dev/memory/retrieve   - Read stored keys (JSON body: agent_id, keys[]?)
POST https://parsebit-lnd.fly.dev/memory/delete     - Delete a key (JSON body: agent_id, key) — free
GET  https://parsebit-lnd.fly.dev/memory/info       - Memory service info and limits (free)

### Agent Suggest (Free — no payment required)
POST https://parsebit-lnd.fly.dev/suggest      - Describe a task, get back a service recommendation + pipeline (free)
GET  https://parsebit-lnd.fly.dev/suggest      - Endpoint info and example inputs (free, crawlable)

### Trial (Free — no Lightning payment required)
POST https://parsebit-lnd.fly.dev/trial/review      - Capped code review, 500 char input, 5 calls/hr/IP
POST https://parsebit-lnd.fly.dev/trial/summarise   - Capped text summary, 1000 char input, 5 calls/hr/IP
GET  https://parsebit-lnd.fly.dev/trial/info        - Trial limits and upgrade guide

### Utility
GET  https://parsebit-lnd.fly.dev/health            - Health check (free)
GET  https://parsebit-lnd.fly.dev/agent-spec.md     - This file (free)

## Summarisation response format
{
  "title": "string or null",
  "summary": "2-3 sentence summary",
  "key_points": ["string", "string", "string"],
  "word_count": 1234,
  "language": "en",
  "sentiment": "positive | negative | neutral",
  "topics": ["string", "string"],
  "_meta": {"input_tokens": 0, "output_tokens": 0, "model": ""}
}

## Code Review response format
{
  "language": "python",
  "overall_score": 7,
  "summary": "2-3 sentence assessment",
  "bugs": [
    {"severity": "critical|high|medium|low", "line": 42,
      "description": "...", "suggestion": "..."}
  ],
  "security_issues": [
    {"severity": "critical|high|medium|low", "line": 10,
      "description": "...", "suggestion": "..."}
  ],
  "code_quality": [
    {"category": "readability|maintainability|performance|style|testing",
      "description": "...", "suggestion": "..."}
  ],
  "strengths": ["what the code does well"],
  "recommended_actions": ["prioritised fix list"],
  "_meta": {"input_tokens": 0, "output_tokens": 0, "model": "", "truncated": false}
}

## Error codes
400 - Could not fetch the URL
413 - File/code too large
415 - Not a PDF (summarise endpoints)
422 - PDF has no extractable text / binary file (review endpoints)
500 - AI error, retry once

## L402 payment flow
1. Make your request normally.
2. Receive HTTP 402 with a Lightning invoice in the WWW-Authenticate header.
3. Pay the invoice with any Lightning wallet or L402-compatible client.
4. Retry with: Authorization: L402 <token>:<preimage>
5. Receive your JSON response.

## Agent discovery
Boltwork is discoverable by any agent that supports the L402 protocol:
- Well-known endpoint: https://parsebit-lnd.fly.dev/.well-known/l402.json
- Listed on the 402 Index: https://402index.io

## Data & privacy
- Documents/code processed on Fly.io servers in London (UK)
- Text sent to Anthropic's API for analysis
- Anthropic does not train on API data by default
- No content stored permanently by this service
- By Cracked Minds — crackedminds.co.uk