API Documentation

ContextZip converts any URL into clean, LLM-ready Markdown. One API call replaces complex HTML parsing pipelines — saving up to 90% on token costs.

Quick Start

Get your first clean Markdown response in under 60 seconds.

1. Get an API key

Log in to the Admin Panel and generate an API key under API Keys.

2. Make your first request

curl -X POST https://contextzip.com/v1/extract \
  -H "X-API-Key: czk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/article","mode":"clean"}'

3. Parse the response

{
  "status": "success",
  "data": {
    "title": "Example Article",
    "markdown": "# Example Article\n\nClean content here...",
    "byline": "John Smith",
    "tokens_saved": 84210,
    "word_count": 1240
  },
  "cached": false,
  "cost": 0.005,
  "mode": "clean"
}

Authentication

All API requests require authentication via an API key passed in the request header.

POST /v1/extract

Synchronously extracts and returns clean Markdown from the provided URL. For very slow pages (>15s render time), consider using async mode.

Request Body

Response

GET /v1/jobs/:jobId

Poll the status and result of an async extraction job.

Job Status Values

GET /health

Returns the health status of all system components.

curl https://contextzip.com/health

{
  "status": "healthy",
  "uptime": 86400,
  "services": {
    "database": "ok",
    "redis": "ok",
    "queue": "ok"
  }
}

Extraction Modes

clean $0.005/req · Recommended

Uses Mozilla Readability to identify and extract only the main article content. Strips ads, navigation, sidebars, footers, cookie banners, and other boilerplate. Best signal-to-noise ratio for LLM ingestion.

raw $0.003/req

Converts the entire rendered page to Markdown. Preserves all content including navigation and sidebar. Use when you need maximum coverage or the page structure is non-standard.

summary $0.001/req

Returns the first 500 tokens of clean content. Ideal for quick page previews, duplicate detection, or when you only need a snippet of the content.

Async Jobs

For pages that take longer than 30 seconds to render, use async mode. Submit the job and poll for completion, or receive a webhook callback.

# 1. Submit async job
curl -X POST https://contextzip.com/v1/extract \
  -H "X-API-Key: czk_your_key" \
  -d '{"url":"https://example.com","async":true,"webhook_url":"https://your.app/webhook"}'

# Response: {"jobId": "job_abc123", "status": "pending"}

# 2. Poll for result
curl https://contextzip.com/v1/jobs/job_abc123 \
  -H "X-API-Key: czk_your_key"

Caching

ContextZip caches all successful extractions for 24 hours per URL+mode combination. Cache hits are:

• Free — $0 cost, regardless of mode
• Fast — Sub-100ms response time
• Shared — Any user's extraction warms the cache for everyone

Check the cached: true field in the response to know if you're receiving a cached result.

Rate Limits

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1709123456

Error Codes

All errors follow this shape:

{
  "status": "error",
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not valid"
  }
}

Pricing