// docs

API Documentation

Everything you need to integrate Ayasofya into your AI agent.

Copy as Markdown
Copy as Text

Quick Start

1. Sign up via GitHub

Visit the dashboard and sign in with GitHub. Accounts older than 1 year get 1,000 free credits/month.

2. Buy credits (PAYG)

curl -X POST https://mcp.ayasofya.yusufgurdogan.com/v1/billing/checkout \
  -H "X-API-Key: ay_live_..." \
  -H "Content-Type: application/json" \
  -d '{"credits": 5000}'

3. Search the web

curl -X POST https://mcp.ayasofya.yusufgurdogan.com/v1/search \
  -H "X-API-Key: ay_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "latest AI news"}'

Authentication

All API requests require an API key in the X-API-Key header.

X-API-Key: ay_live_your_key_here

MCP Model Context Protocol

Connect Ayasofya directly to Claude Code, Cursor, or any MCP-compatible client. Your AI agent gets search, fetch, extract, and research tools, no REST calls needed.

Go to your dashboard and click the copy button for your client. The command is pre-filled with your API key.

Claude Code

claude mcp add --transport http ayasofya https://mcp.ayasofya.yusufgurdogan.com/mcp \
  --header "X-API-Key: ay_live_..."

Cursor · ~/.cursor/mcp.json

{
  "mcpServers": {
    "ayasofya": {
      "url": "https://mcp.ayasofya.yusufgurdogan.com/mcp",
      "headers": { "X-API-Key": "ay_live_..." }
    }
  }
}

Codex · ~/.codex/config.toml

[mcp_servers.ayasofya]
url = "https://mcp.ayasofya.yusufgurdogan.com/mcp"
http_headers = { "X-API-Key" = "ay_live_..." }

Windsurf · ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "ayasofya": {
      "serverUrl": "https://mcp.ayasofya.yusufgurdogan.com/mcp",
      "headers": { "X-API-Key": "ay_live_..." }
    }
  }
}

VS Code Copilot · .vscode/mcp.json

{
  "servers": {
    "ayasofya": {
      "type": "http",
      "url": "https://mcp.ayasofya.yusufgurdogan.com/mcp",
      "headers": { "X-API-Key": "ay_live_..." }
    }
  }
}

Your API key is sent via HTTP header. The AI model never sees it.

Available Tools

search

Web search with page content extraction and optional AI answers. 1-10 credits.

fetch

Full page content as clean markdown. 1 credit.

extract

AI-powered structured data extraction. 5 credits.

research

Multi-query deep research with AI synthesis. 25 credits.

Core Tools

POST /v1/fetch 1 credit

Fetch any webpage as clean markdown content.

Request Body

{
  "url": "string"           // required
}

Response

{
  "title": "Example Page",
  "url": "https://example.com",
  "content": "# Markdown content...",
  "published_time": "2024-01-01T00:00:00Z",
  "credits_used": 1,
  "credits_remaining": 999
}
curl -X POST https://mcp.ayasofya.yusufgurdogan.com/v1/fetch \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ay_live_..." \
  -d '{"url": "https://example.com"}'
import httpx

resp = httpx.post("https://mcp.ayasofya.yusufgurdogan.com/v1/fetch",
    headers={"X-API-Key": "ay_live_..."},
    json={"url": "https://example.com"})
print(resp.json())
const resp = await fetch("https://mcp.ayasofya.yusufgurdogan.com/v1/fetch", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": "ay_live_..." },
  body: JSON.stringify({ url: "https://example.com" })
});
console.log(await resp.json());
POST /v1/extract 5 credits

Fetch a webpage and extract specific information using AI. Requires a paid plan (Builder or above).

Request Body

{
  "url": "string",          // required
  "prompt": "string"        // required, what to extract
}

Response

{
  "content": "Extracted information...",
  "url": "https://example.com",
  "credits_used": 5,
  "credits_remaining": 995,
  "usage": { "input_tokens": 90, "output_tokens": 24 }
}
curl -X POST https://mcp.ayasofya.yusufgurdogan.com/v1/extract \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ay_live_..." \
  -d '{"url": "https://example.com", "prompt": "Summarize this page"}'
import httpx

resp = httpx.post("https://mcp.ayasofya.yusufgurdogan.com/v1/extract",
    headers={"X-API-Key": "ay_live_..."},
    json={"url": "https://example.com", "prompt": "Summarize this page"})
print(resp.json())
const resp = await fetch("https://mcp.ayasofya.yusufgurdogan.com/v1/extract", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": "ay_live_..." },
  body: JSON.stringify({ url: "https://example.com", prompt: "Summarize this page" })
});
console.log(await resp.json());
POST /v1/research 25 credits

Deep research on any topic. Decomposes your query into sub-queries, searches and reads multiple sources in parallel, then synthesizes a structured report with citations. Requires a paid plan (Builder or above).

Request Body

{
  "query": "string",              // required
  "topic": "general",             // "general" or "news"
  "freshness": null,              // "day", "week", "month", "year", or "YYYY-MM-DD:YYYY-MM-DD"
  "max_sources": 20               // 5-30
}

Response

{
  "query": "How do modern LLMs handle long context?",
  "report": "## Key Findings\n\n- ...",
  "sources": [
    {
      "title": "Scaling Transformer Context Windows",
      "url": "https://arxiv.org/abs/...",
      "fetched": true
    }
  ],
  "sub_queries": [
    "transformer context window scaling techniques",
    "RoPE positional encoding extensions"
  ],
  "credits_used": 25,
  "credits_remaining": 975,
  "usage": { "input_tokens": 12400, "output_tokens": 1850 }
}
curl -X POST https://mcp.ayasofya.yusufgurdogan.com/v1/research \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ay_live_..." \
  -d '{"query": "How do modern LLMs handle long context?"}'
import httpx

resp = httpx.post("https://mcp.ayasofya.yusufgurdogan.com/v1/research",
    headers={"X-API-Key": "ay_live_..."},
    json={"query": "How do modern LLMs handle long context?"},
    timeout=120)
print(resp.json())
const resp = await fetch("https://mcp.ayasofya.yusufgurdogan.com/v1/research", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": "ay_live_..." },
  body: JSON.stringify({ query: "How do modern LLMs handle long context?" })
});
console.log(await resp.json());

Account

GET /v1/auth/me

Get your account info including plan, credits, and total requests.

Response

{
  "plan": "free",
  "credits": 997,
  "credits_reset_at": "2026-04-04T12:00:00Z",
  "total_requests": 3,
  "api_key": "ay_live_...",
  "last_login_method": "github",
  "email": "user@example.com",
  "github_username": "octocat"
}
GET /v1/auth/transactions

Get your recent credit transactions (top-ups). Returns the last 50.

Response

[
  {
    "id": "uuid",
    "type": "credit",
    "amount": 5000,
    "endpoint": "top-up",
    "balance_after": 6000,
    "created_at": "2026-02-22T12:00:00Z"
  }
]
GET /v1/auth/usage

Get your daily usage breakdown. Returns the last 30 days, per endpoint.

Response

[
  {
    "date": "2026-02-22",
    "endpoint": "/v1/search",
    "request_count": 312,
    "total_credits": 312
  }
]

Billing

POST /v1/billing/checkout

Buy credits (PAYG). Minimum purchase: 2,000 credits ($10). Redirects to payment page.

Request Body

{
  "credits": 5000           // required, minimum ~2000
}

Response

{
  "checkout_url": "https://checkout.creem.io/pay/..."
}