Capture API
Personal capture API for saving notes/links from Apple Shortcuts. Built with Bun, Hono, SQLite.
Installation
npx capture-apiAsk AI about Capture API
Powered by Claude Β· Grounded in docs
I know everything about Capture API. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Capture API
A personal capture API designed for saving quick notes, links, and thoughts from Apple Shortcuts. Built with Bun, Hono, and SQLite for persistence.
Overview
This API serves as a personal inbox for capturing anything from my iPhone via Apple Shortcuts. It provides:
- REST API - Simple endpoints for saving and retrieving captures
- API Key Auth - Bearer token authentication for security
- SQLite Storage - Persistent local database
- MCP Server - Access captures from Claude via MCP protocol
Features
Core Capture API
-
Create Capture -
POST /api/captures- Accept text content, optional title, optional URL
- Auto-generate timestamp
- Support tags (comma-separated)
- Return created capture with ID
-
List Captures -
GET /api/captures- Return all captures, newest first
- Support
?limit=Nquery param - Support
?tag=tagnamefiltering - Support
?search=termfull-text search
-
Get Single Capture -
GET /api/captures/:id- Return single capture by ID
- 404 if not found
-
Delete Capture -
DELETE /api/captures/:id- Soft delete (mark as deleted)
- 404 if not found
Authentication
-
API Key Setup
- Generate API key on first run (save to
.env) - Read from
CAPTURE_API_KEYenv var - Require
Authorization: Bearer <key>header
- Generate API key on first run (save to
-
Auth Middleware
- Validate bearer token on all
/api/*routes - Return 401 for missing/invalid token
- Skip auth for health check endpoint
- Validate bearer token on all
Health & Status
-
Health Check -
GET /health- No auth required
- Return
{ status: "ok", timestamp: "..." }
-
Stats Endpoint -
GET /api/stats- Total capture count
- Captures this week
- Top tags
MCP Server
-
List Captures Tool
list_captures- Get recent captures- Parameters: limit (optional), tag (optional)
-
Search Captures Tool
search_captures- Full-text search- Parameters: query (required)
-
Create Capture Tool
create_capture- Add new capture- Parameters: content (required), title, url, tags
Tech Stack
- Runtime: Bun
- Framework: Hono (lightweight web framework)
- Database: SQLite via bun:sqlite
- Auth: Bearer token (API key)
- MCP: @modelcontextprotocol/sdk
Database Schema
CREATE TABLE captures (
id TEXT PRIMARY KEY,
content TEXT NOT NULL,
title TEXT,
url TEXT,
tags TEXT, -- JSON array
created_at TEXT NOT NULL,
deleted_at TEXT
);
CREATE INDEX idx_captures_created ON captures(created_at DESC);
CREATE INDEX idx_captures_deleted ON captures(deleted_at);
API Examples
Create a capture (from Apple Shortcuts)
curl -X POST http://localhost:3000/api/captures \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"content": "Interesting article about AI agents",
"url": "https://example.com/article",
"tags": ["reading", "ai"]
}'
List recent captures
curl http://localhost:3000/api/captures?limit=10 \
-H "Authorization: Bearer $API_KEY"
Search captures
curl http://localhost:3000/api/captures?search=ai \
-H "Authorization: Bearer $API_KEY"
Project Structure
capture-api/
βββ src/
β βββ index.ts # Main entry, server setup
β βββ routes/
β β βββ captures.ts # Capture CRUD routes
β β βββ health.ts # Health check route
β βββ middleware/
β β βββ auth.ts # API key validation
β βββ db/
β β βββ schema.ts # Database initialization
β β βββ queries.ts # Database operations
β βββ mcp/
β βββ server.ts # MCP server implementation
βββ tests/
β βββ captures.test.ts # API tests
β βββ auth.test.ts # Auth tests
βββ package.json
βββ tsconfig.json
βββ README.md
Running
# Development
bun run dev
# Production
bun run src/index.ts
# Run MCP server
bun run src/mcp/server.ts
Environment Variables
CAPTURE_API_KEY=<generated-on-first-run>
CAPTURE_DB_PATH=./captures.db
PORT=3000
