API Reference
Complete API documentation for Skimly's endpoints. All endpoints support both raw HTTP requests and our official SDKs for Node.js and Python.
Production: https://api.skimly.dev
Development: http://localhost:8000
Authentication: X-API-Key: YOUR_API_KEY (preferred) or Authorization: Bearer YOUR_API_KEY
SDK Environment: export SKIMLY_BASE=https://api.skimly.dev for production API
Authentication
All API requests require authentication using your Skimly API key. We recommend using theX-API-Key header for best performance, though Authorization Bearer tokens are also supported.
Header Format
# Option 1: X-API-Key header (recommended) X-API-Key: YOUR_API_KEY # Option 2: Authorization Bearer token Authorization: Bearer YOUR_API_KEY
SDK Usage
# Set environment variable export SKIMLY_KEY="YOUR_API_KEY" # SDKs automatically read it const client = SkimlyClient.fromEnv()
API Key Management
Create and manage your API keys through the dashboard or programmatically:
Create API Key
POST /v1/keys
{
"name": "My App Key"
}
Response:
{
"id": "sk_...",
"name": "My App Key",
"key": "sk-proj-...",
"created_at": "2025-01-01T00:00:00Z"
}List API Keys
GET /v1/keys
Response:
{
"keys": [
{
"id": "sk_...",
"name": "My App Key",
"last_four": "ab12",
"created_at": "2025-01-01T00:00:00Z"
}
]
}Authentication Errors
Common authentication error responses:
Chat Completions
Send chat requests to any supported provider (OpenAI or Anthropic). Messages can include text content or blob pointers for efficient context handling.
POST /v1/chat
Parameters
provider"openai" | "anthropic" (required)modelModel name (required)messagesArray of message objects (required)temperature0.0 to 2.0 (optional)max_tokensMaximum response tokens (optional)mode"compact" | "verbose" (optional, default: "compact")Example Request
// npm i @skimly/sdk@^2.0.0
import { SkimlyClient } from '@skimly/sdk'
const client = new SkimlyClient({
apiKey: process.env.SKIMLY_KEY!,
baseURL: 'http://localhost:8000'
})
// Anthropic-style interface with compression
const message = await client.messages.create({
provider: 'openai',
model: 'gpt-4o-mini',
max_tokens: 1024,
messages: [{ role: 'user', content: 'Hello from Node!' }]
})
console.log(message.content[0].text)
console.log('Tokens saved:', message.skimly_meta?.tokens_saved)Blob Management
Create and manage blobs for storing large content that can be referenced in chat requests.
POST /v1/blobs
Parameters
contentBlob content (required)mime_typeContent type (optional, default: "text/plain")Example Request
// npm i @skimly/sdk@^2.0.0
import { SkimlyClient } from '@skimly/sdk'
const client = new SkimlyClient({
apiKey: process.env.SKIMLY_KEY!,
baseURL: 'http://localhost:8000'
})
const blob = await client.createBlob('big content...', 'text/plain')
console.log('Blob ID:', blob.blob_id)
// Idempotent upload (avoids duplicates)
const dedupedBlob = await client.createBlobIfNew('big content...', 'text/plain')
console.log('Deduped Blob ID:', dedupedBlob.blob_id)Fetch Blob Content
Retrieve blob content with optional range support for efficient partial reads.
GET /v1/fetch
Query Parameters
refBlob reference (required)startStart byte offset (optional)endEnd byte offset (optional, max 8KB range)Example Request
# Full blob read curl -H "X-API-Key: YOUR_API_KEY" \ "http://localhost:8000/v1/fetch?ref=b_abc123" # Range read (first 1KB) curl -H "X-API-Key: YOUR_API_KEY" \ "http://localhost:8000/v1/fetch?ref=b_abc123&start=0&end=1024"
Content Transformation
Transform and compress tool results using Smart Compression Timing technology.
POST /v1/transform
Parameters
resultTool result content (required)tool_nameName of the tool (optional)commandCommand executed (optional)modelModel for token calculation (optional, default: "gpt-4")Example Request
curl -X POST "http://localhost:8000/v1/transform" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"result": "Large tool output content...",
"tool_name": "bash",
"command": "npm run build",
"model": "gpt-4"
}'Signed URLs
Generate secure, time-limited URLs for direct blob access.
GET /v1/blob/{ref}/signed
Query Parameters
ttlTTL in seconds (default: 3600, max: 7200)Example Request
curl -H "X-API-Key: YOUR_API_KEY" \ "http://localhost:8000/v1/blob/b_abc123/signed?ttl=1800"
API Key Management
Manage your API keys for authentication and usage tracking.
GET /v1/keys
List all API keys for the authenticated user.
curl -H "X-API-Key: YOUR_API_KEY" \ "http://localhost:8000/v1/keys"
POST /v1/keys
Create a new API key.
curl -X POST "http://localhost:8000/v1/keys" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "My New Key"}'DELETE /v1/keys/{key_id}
Revoke an API key.
curl -X DELETE "http://localhost:8000/v1/keys/key_123" \ -H "X-API-Key: YOUR_API_KEY"
POST /v1/keys/{key_id}
Perform key operations (rotate, reveal).
# Rotate key
curl -X POST "http://localhost:8000/v1/keys/key_123" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"op": "rotate"}'Smart Compression Technology
Skimly uses advanced AI-powered compression that goes beyond simple size thresholds:
Smart Timing
Predicts when users will access content based on tool context and content analysis.
Content Analysis
Detects patterns in build logs, error stacks, diffs, and other development content.
Cost Optimization
Prevents negative savings by analyzing deref costs before compression.
Session Tracking
Tracks compression decisions and calculates real ROI across user sessions.
Use mode: "compact" in chat requests to enable Smart Compression Timing. This automatically applies the most efficient compression strategy based on content analysis.