Ox API Documentation

Base URL: https://ox.aikode.org/fetch.php

Ox extracts main content from any URL and returns clean GitHub Flavored Markdown. Save 27-60% tokens vs raw HTML.

Authentication

All requests require an API key passed via HTTP header:

X-Ox-Key: YOUR_API_KEY

Important: Never include your API key in URL parameters. Always use the HTTP header.

Quick Start

cURL

curl -H "X-Ox-Key: YOUR_API_KEY" \
  "https://ox.aikode.org/fetch.php?url=https://example.com"

Python

import requests

headers = {'X-Ox-Key': 'YOUR_API_KEY'}
params = {'url': 'https://example.com'}

response = requests.get(
    'https://ox.aikode.org/fetch.php',
    headers=headers,
    params=params
)

markdown = response.text
print(markdown)

JavaScript

const response = await fetch(
  'https://ox.aikode.org/fetch.php?url=https://example.com',
  {
    headers: {
      'X-Ox-Key': 'YOUR_API_KEY'
    }
  }
);

const markdown = await response.text();
console.log(markdown);

Parameters

Parameter	Required	Description
`url`	Yes	The URL to fetch and convert. Must be URL-encoded.

URL Encoding: Always encode the URL parameter. For example:
?url=https%3A%2F%2Fexample.com%2Farticle%3Fid%3D123

Response Format

Returns plain text in GitHub Flavored Markdown format:

# Page Title

Main content starts here...

## Subheading

More content with [links](https://example.com) and **formatting**.

### Tables

| Column 1 | Column 2 |
|----------|----------|
| Data     | More     |

Response Headers

Header	Description	Example
`X-Ox-Cache`	Cache status	HIT or MISS
`X-Ox-Title`	Extracted page title	Example Article
`X-Ox-Limit`	Your monthly limit	500
`X-Ox-Used`	Requests used this month	42
`X-Ox-Remaining`	Requests remaining	458

Cached requests don't count toward your limit! If you fetch the same URL within 1 hour, you'll get a cached response (X-Ox-Cache: HIT) and it won't use your quota.

Error Codes

Code	Error	Description
`400`	Bad Request	Missing or invalid `url` parameter
`401`	Unauthorized	Invalid or missing API key
`429`	Rate Limit	Monthly limit reached
`500`	Server Error	Pandoc conversion failed
`502`	Bad Gateway	Failed to fetch target URL

Examples

Fetch Wikipedia Article

curl -H "X-Ox-Key: YOUR_API_KEY" \
  "https://ox.aikode.org/fetch.php?url=https://en.wikipedia.org/wiki/Rust_(programming_language)"

# Returns:
# Rust (programming language)
# 
# **Rust** is a general-purpose programming language...
# (Note: Infobox table is automatically removed)

Check Usage Headers

curl -I -H "X-Ox-Key: YOUR_API_KEY" \
  "https://ox.aikode.org/fetch.php?url=https://example.com"

# Response includes:
# X-Ox-Cache: MISS
# X-Ox-Limit: 500
# X-Ox-Used: 43
# X-Ox-Remaining: 457

Rate Limits

Beta Plan: 500 requests/month

Limit resets on the 1st of each month
Cached requests (HIT) don't count toward limit
Cache TTL: 1 hour
When you hit the limit, you'll get a 429 error with reset date

Best Practices

When to Use Ox

✅ Fetching articles, blog posts, documentation
✅ Multi-source research (token savings really add up)
✅ Wikipedia research (infobox removal is a big win)
✅ Content aggregation and curation
✅ RAG systems that need clean markdown

When NOT to Use Ox

❌ Fetching raw data (JSON, XML, CSV)
❌ Binary files (PDFs, images, videos)
❌ Sites requiring authentication
❌ Interactive web applications

Optimization Tips

Cache awareness: Same URL within 1 hour = free cached response
Token savings: Wikipedia articles: ~60% savings, news sites: ~30-40%
Batch processing: Cache popular URLs during off-hours for instant access
URL encoding: Always encode URLs with special characters

Token Efficiency

Method	Est. Tokens	Savings
Raw HTML	~120,000	baseline
Readability HTML	~80,000	33%
Ox Markdown	~58,000	52%

Based on Wikipedia article testing. Savings vary by site.

Need Help?

Questions or issues? We're here to help:

📧 Email: feedback@aikode.org
💬 Feedback form: feedback.html
🏠 Homepage: ox.aikode.org

Ox Docs