Agent Integration Guide

# Step 1: Register
curl -s -X POST "https://cdn.aisa.one/api/agent/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "MySecurePass123",
    "name": "MyBot",
    "crawlerType": "custom",
    "companyName": "Acme Inc"
  }'
# Response: { "success": true, "crawler": { "crawlerToken": "aisa_crawler_xxx", ... } }

# Step 2: Top up (via dashboard or API - see Top-up section)

# Step 3: Access content
curl -s -X POST "https://cdn.aisa.one/api/v1/access/verify" \
  -H "Content-Type: application/json" \
  -H "X-AISA-Crawler-Token: aisa_crawler_xxx" \
  -d '{
    "publisherDomain": "[email protected]",
    "resourceUrl": "/article/2026/ai-trends.html",
    "crawlerAutoPrice": true
  }'
# Response: { "accessGranted": true, "statusCode": 200, "charge": { "amount": 0.01 } }

curl -s -X POST "https://cdn.aisa.one/api/agent/auth/register" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "SecurePass888",
    "name": "MySearchBot",
    "crawlerType": "custom",
    "userAgent": "MySearchBot/1.0",
    "companyName": "Acme AI Labs"
  }'

{
  "success": true,
  "token": "eyJjcmF3bGVySWQ...",       // Session token (for dashboard login)
  "crawler": {
    "id": 42,
    "crawlerUuid": "crawler-a1b2c3d4-1712345678",
    "email": "[email protected]",
    "name": "MySearchBot",
    "crawlerType": "custom",
    "crawlerToken": "aisa_crawler_abc123def456...",  // API token (use this for access/verify)
    "balance": 0,
    "totalSpent": 0
  }
}

curl -s -X POST "https://cdn.aisa.one/api/agent/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "password": "SecurePass888" }'

# Step 1: Login to get session token
SESSION_TOKEN=$(curl -s -X POST "https://cdn.aisa.one/api/agent/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"SecurePass888"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")

# Step 2: Create Stripe checkout session
curl -s -X POST "https://cdn.aisa.one/api/agent/topup/create-session" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -d '{"amount": 5.00}'

# Response includes: { "sessionId": "cs_xxx", "url": "https://checkout.stripe.com/..." }
# Open the URL to complete payment. Balance is added automatically after payment.

curl -s "https://cdn.aisa.one/api/agent/info" \
  -H "Authorization: Bearer $SESSION_TOKEN"
# Response: { "crawler": { "balance": "5.000000", ... } }

{
  "accessGranted": true,
  "statusCode": 200,
  "message": "Access granted - charge applied",
  "charge": {
    "amount": 0.01,
    "currency": "USD",
    "billingType": "per-request",
    "crawlerBalanceBefore": 5.00,
    "crawlerBalanceAfter": 4.99
  },
  "rule": {
    "id": 10,
    "urlPattern": "/article/",
    "accessMode": "pay",
    "price": 0.01
  },
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "custom"
  }
}

{
  "accessGranted": false,
  "statusCode": 402,
  "error": "insufficient_balance",
  "message": "Insufficient balance",
  "price": {
    "amount": 0.01,
    "currency": "USD",
    "billingType": "per-request"
  },
  "crawler": {
    "currentBalance": 0.00,
    "shortfall": 0.01
  },
  "onboarding": "https://cdn.aisa.one/cdn/guide.html",
  "crawlerIdentification": {
    "recognized": true,
    "identifier": "custom"
  }
}

# Option A: Just auto-pay (simplest)
response = access_verify(token, publisher, url, autoPrice=true)

# Option B: Discover price first, then confirm
response = access_verify(token, publisher, url)  # no price param
if response.statusCode == 402 and response.price:
    price = response.price.amount
    if price <= my_budget:
        response = access_verify(token, publisher, url, exactPrice=f"USD {price}")

# Option C: Set max budget
response = access_verify(token, publisher, url, maxPrice="USD 0.50")

import requests

BASE_URL = "https://cdn.aisa.one"
TOKEN = "aisa_crawler_xxx"

def access_content(publisher, url):
    resp = requests.post(f"{BASE_URL}/api/v1/access/verify", json={
        "publisherDomain": publisher,
        "resourceUrl": url,
        "crawlerAutoPrice": True
    }, headers={"Authorization": f"Bearer {TOKEN}"})

    data = resp.json()

    if data.get("accessGranted"):
        return data  # Success

    error = data.get("error")

    if error == "insufficient_balance":
        print(f"Balance low. Need ${data['crawler']['shortfall']} more.")
        print(f"Top up at: {BASE_URL}/agent/wallet.html")
        # TODO: auto top-up via Stripe API
        return None

    if error == "price_required":
        # Price discovery mode - now we know the price, retry with auto
        print(f"Price: ${data['price']['amount']} - retrying with auto-pay")
        return access_content(publisher, url)  # Will auto-pay on retry

    if error == "invalid_token":
        print("Token invalid. Please register or check token.")
        return None

    print(f"Access denied: {error} - {data.get('message')}")
    return None

// Node.js example
const BASE_URL = "https://cdn.aisa.one";
const TOKEN = "aisa_crawler_xxx";

async function accessContent(publisher, resourceUrl) {
  const resp = await fetch(`${BASE_URL}/api/v1/access/verify`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${TOKEN}`
    },
    body: JSON.stringify({
      publisherDomain: publisher,
      resourceUrl: resourceUrl,
      crawlerAutoPrice: true
    })
  });

  const data = await resp.json();

  if (data.accessGranted) {
    console.log(`Access granted. Charged: $${data.charge?.amount}`);
    return data;
  }

  switch (data.error) {
    case "insufficient_balance":
      console.log(`Need $${data.crawler?.shortfall} more. Top up at /agent/wallet.html`);
      break;
    case "invalid_token":
      console.log("Invalid token. Register at /api/agent/auth/register");
      break;
    default:
      console.log(`Denied: ${data.error} - ${data.message}`);
  }
  return null;
}

#!/bin/bash
BASE="https://cdn.aisa.one"
TOKEN="aisa_crawler_YOUR_TOKEN_HERE"

# Auto-pay mode
curl -s -X POST "$BASE/api/v1/access/verify" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "publisherDomain": "[email protected]",
    "resourceUrl": "/premium/article.html",
    "crawlerAutoPrice": true
  }' | python3 -m json.tool

import requests

class AISAClient:
    def __init__(self, token, base_url="https://cdn.aisa.one"):
        self.token = token
        self.base_url = base_url
        self.headers = {
            "Content-Type": "application/json",
            "Authorization": f"Bearer {token}"
        }

    def access(self, publisher, resource_url, auto_price=True):
        payload = {
            "publisherDomain": publisher,
            "resourceUrl": resource_url,
        }
        if auto_price:
            payload["crawlerAutoPrice"] = True

        resp = requests.post(
            f"{self.base_url}/api/v1/access/verify",
            json=payload,
            headers=self.headers
        )
        return resp.json()

    def get_balance(self, session_token):
        resp = requests.get(
            f"{self.base_url}/api/agent/info",
            headers={"Authorization": f"Bearer {session_token}"}
        )
        return resp.json()

# Usage
client = AISAClient("aisa_crawler_YOUR_TOKEN")
result = client.access("[email protected]", "/article/2026/trends.html")

if result["accessGranted"]:
    print(f"Granted! Charged: ${result['charge']['amount']}")
else:
    print(f"Denied: {result['error']} - {result.get('message')}")

class AISAClient {
  constructor(token, baseUrl = "https://cdn.aisa.one") {
    this.token = token;
    this.baseUrl = baseUrl;
  }

  async access(publisher, resourceUrl, { autoPrice = true } = {}) {
    const body = { publisherDomain: publisher, resourceUrl };
    if (autoPrice) body.crawlerAutoPrice = true;

    const resp = await fetch(`${this.baseUrl}/api/v1/access/verify`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${this.token}`
      },
      body: JSON.stringify(body)
    });
    return resp.json();
  }
}

// Usage
const client = new AISAClient("aisa_crawler_YOUR_TOKEN");
const result = await client.access("[email protected]", "/article/test.html");
console.log(result.accessGranted ? "Granted" : `Denied: ${result.error}`);