API Documentation

Everything you need to integrate Ayasofya into your AI agent.

Quick Start

1. Register for an API key

curl -X POST https://ayasofya.yusufgurdogan.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]"}'

2. Top up your balance

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

3. Search the web

curl -X POST https://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 (except registration and status) require an API key in the X-API-Key header.

X-API-Key: ay_live_your_key_here

Core Tools

POST /v1/search $0.001/request

Search the web. Returns structured results optimized for AI agents.

Request Body

{
  "query": "string",        // required
  "num_results": 10         // optional, 1-50
}

Response

{
  "results": [
    { "title": "...", "url": "...", "description": "...", "date": "..." }
  ],
  "related": ["..."],
  "cost": 0.001,
  "balance_remaining": 24.999
}

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

import httpx

resp = httpx.post("https://ayasofya.yusufgurdogan.com/v1/search",
    headers={"X-API-Key": "ay_live_..."},
    json={"query": "latest AI news", "num_results": 10})
print(resp.json())

const resp = await fetch("https://ayasofya.yusufgurdogan.com/v1/search", {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-API-Key": "ay_live_..." },
  body: JSON.stringify({ query: "latest AI news", num_results: 10 })
});
console.log(await resp.json());

POST /v1/fetch $0.001/request

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",
  "cost": 0.001,
  "balance_remaining": 24.998
}

curl -X POST https://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://ayasofya.yusufgurdogan.com/v1/fetch",
    headers={"X-API-Key": "ay_live_..."},
    json={"url": "https://example.com"})
print(resp.json())

const resp = await fetch("https://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());

Account

POST /v1/auth/register Free

Create a new account and receive an API key.

Request Body

{
  "email": "string"         // required
}

Response

{
  "api_key": "ay_live_...",
  "email": "[email protected]",
  "balance": 0.0
}

GET /v1/auth/me

Get your account info including current balance and total requests.

Response

{
  "email": "[email protected]",
  "balance": 24.997,
  "total_requests": 3
}

GET /v1/auth/transactions

Get your recent transaction history. Returns the last 50 transactions.

Response

[
  {
    "id": 1,
    "type": "debit",
    "amount": 0.001,
    "endpoint": "/v1/search",
    "balance_after": 24.999,
    "created_at": "2025-01-15T12:00:00Z"
  }
]

Billing

POST /v1/billing/checkout

Create a checkout session to top up your balance. Minimum $10. Redirects to payment page.

Request Body

{
  "amount": 25              // required, minimum 10
}

Response

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

System

GET /v1/status Free

Check the health of all services. No authentication required.

Response

{
  "status": "operational",
  "uptime_24h": 99.95,
  "uptime_7d": 99.98,
  "uptime_30d": 99.99,
  "services": {
    "search": { "status": "up", "latency_ms": 245 },
    "fetch": { "status": "up", "latency_ms": 1023 }
  }
}