Fabric REST API: Complete Guide to HTTP Interface and Endpoints

Yes, Fabric provides a built-in REST API that exposes all core functionality—including chat completions, pattern management, and YouTube transcript extraction—via HTTP endpoints that can be started with the --serve flag and optionally secured with API keys.

The danielmiessler/fabric repository ships with a comprehensive REST API server that transforms the CLI tool into a programmable HTTP service. This built-in interface allows developers to integrate Fabric's AI capabilities into external applications without shelling out to the command line. The server implementation resides in the internal/server directory and follows standard REST conventions with OpenAPI documentation.

Starting the Fabric REST API Server

Launch the HTTP server using the --serve flag. By default, the server binds to http://localhost:8080.

fabric --serve

To protect the endpoints, supply an API key during startup. The server will warn you if started without authentication (see internal/server/serve.go lines 36-40).

fabric --serve --api-key my_secret_key

When authentication is enabled, clients must include the X-API-Key header in all requests except for the Swagger documentation endpoints.

Architecture and Source Code Structure

The REST implementation uses the Gin web framework and follows a modular handler pattern. Each resource type has a dedicated source file in internal/server/.

Server Initialization (internal/server/serve.go)

The serve.go file bootstraps the Gin engine, attaches middleware, and registers all route handlers. This is the entry point that wires together authentication, CORS, and the individual endpoint controllers.

Authentication Middleware (internal/server/auth.go)

API security is implemented in auth.go. The middleware checks for the X-API-Key header and aborts with HTTP 401 when the key is missing or invalid. Notably, the Swagger UI routes remain publicly accessible even when API-key protection is active (see auth.go lines 17-22).

Chat Streaming Endpoint (internal/server/chat.go)

The /chat endpoint handles Server-Sent Events (SSE) for real-time AI response streaming. The handler binds incoming JSON requests, injects language preferences and model options, invokes the core chatter logic, and writes chunked SSE responses. The stream emits JSON objects of type content, usage, error, or complete (see chat.go lines 70-90 and the writeSSEResponse helper).

Resource Handlers

Individual files manage specific domains:

• patterns.go – CRUD operations for Fabric patterns
• contexts.go – Context management and storage
• sessions.go – Session state handling
• models.go – Available model listings
• youtube.go – YouTube transcript extraction
• config.go – Runtime configuration access

Key API Endpoints and Usage Examples

Pattern Management

List all available patterns:

curl http://localhost:8080/patterns/names

Retrieve a specific pattern definition:

curl http://localhost:8080/patterns/summarize

Apply a pattern with variables:

curl -X POST http://localhost:8080/patterns/translate/apply \
     -H "Content-Type: application/json" \
     -d '{
           "input": "Hello world",
           "variables": {"lang_code": "es"}
         }'

Chat Completions (SSE Streaming)

The chat endpoint accepts a prompts array and streams responses. This example demonstrates multi-turn interaction with explicit vendor and model selection:

curl -X POST http://localhost:8080/chat \
     -H "Content-Type: application/json" \
     -d '{
           "prompts": [{
             "userInput": "Explain quantum computing",
             "vendor": "openai",
             "model": "gpt-5.2",
             "patternName": "explain"
           }],
           "language": "en",
           "temperature": 0.7,
           "topP": 0.9
         }'

The response streams as SSE data: lines containing JSON fragments that clients must parse incrementally.

YouTube Transcript Extraction

Extract transcripts with optional timestamp inclusion:

curl -X POST http://localhost:8080/youtube/transcript \
     -H "Content-Type: application/json" \
     -d '{"url":"https://youtube.com/watch?v=dQw4w9WgXcQ","timestamps":true}'

Authenticated Requests

When the server runs with --api-key, include the header in all API calls:

curl -H "X-API-Key: my_secret_key" http://localhost:8080/patterns/names

Interactive Documentation

Fabric serves auto-generated OpenAPI documentation via Swagger UI at:

http://localhost:8080/swagger/index.html

Raw specification files are available at /swagger/doc.json and /swagger/swagger.yaml. The human-readable guide in docs/rest-api.md provides additional context, quick-start instructions, and curl examples for common workflows. The OpenAPI specification is defined in docs/swagger.yaml and was generated using swaggo annotations throughout the handler source code.

Summary

• Fabric includes a complete REST API accessible via the --serve flag, exposing all CLI functionality over HTTP.
• Source code for the server lives in internal/server/ with modular handlers for patterns, chat, contexts, sessions, models, YouTube, and configuration.
• Authentication is optional via --api-key, enforced by middleware in auth.go that validates the X-API-Key header while leaving Swagger UI public.
• Chat responses stream using Server-Sent Events (SSE) from the endpoint defined in chat.go, supporting real-time content delivery.
• Documentation is interactive at /swagger/index.html and backed by the OpenAPI spec in docs/swagger.yaml.

Frequently Asked Questions

How do I start the Fabric REST API server?

Run fabric --serve from your terminal. The server starts on port 8080 by default. For production deployments, start with fabric --serve --api-key your_secret_key to require authentication on all endpoints except the Swagger documentation.

Is the Fabric REST API secured by default?

No. According to internal/server/serve.go, the server logs a security warning when started without the --api-key flag. While unprotected servers work for local development, production instances should always specify an API key to prevent unauthorized access to the chat and pattern endpoints.

What data format does the Fabric chat endpoint return?

The /chat endpoint returns Server-Sent Events (SSE)—a text/event-stream where each line starts with data: followed by a JSON object. As implemented in internal/server/chat.go, these objects have a type field (content, usage, error, or complete) and a body field containing the actual payload. Clients must parse this stream incrementally rather than expecting a single JSON response.

Can I access the API documentation without an API key?

Yes. The Swagger UI at /swagger/index.html and the underlying OpenAPI JSON/YAML files are explicitly exempt from API-key validation (see internal/server/auth.go lines 17-22). This design allows developers to explore the endpoint contracts even on secured servers, though executing requests still requires the X-API-Key header when authentication is enabled.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}