API Reference

API Overview

The aposema.com API provides programmatic access to our AI content licensing platform. Use it to verify licenses, log usage, and manage creator accounts.

Base URL

https://api.aposema.com/v1

AI License Ledger (High Performance)

https://ledger.aposema.com/v1

For real-time license discovery and usage logging with sub-50ms response times.

Content Types

All requests and responses use JSON:

Content-Type: application/json

Authentication

API Key Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

HMAC Signature (Usage Logging)

For tamper-proof usage logging, include HMAC signature:

X-HMAC-Signature: sha256=SIGNATURE
X-Timestamp: 1698765432

Getting API Keys

1. Sign in to the AI portal at portal.aposema.com
2. Open API Keys
3. Generate a new key with appropriate scopes
4. Store securely - keys are only shown once

License Verification

{
  "url": "https://example.com/article.html",
  "stage": "infer",
  "distribution": "public"
}

{
  "licensed": true,
  "action": "allow",
  "distribution": "public",
  "price": 0.15,
  "payto": "apo-8f4a2b9c1d5e6f7a",
  "license_version_id": 463781,
  "license_sig": "a3f2d8e9b1c4...",
  "source": "meta_tag",
  "stage_overrides": {
    "train": "deny",
    "infer": {
      "action": "allow",
      "price": 0.15
    }
  }
}

{
  "domain": "example.com",
  "ai_txt": {
    "found": true,
    "url": "https://example.com/ai-license.txt",
    "default_action": "allow",
    "default_price": 0.10
  },
  "meta_tags": {
    "found": true,
    "licenses": [
      {
        "tag": "ai-license",
        "content": "allow;distribution:public;price:0.15"
      }
    ]
  },
  "verified": true,
  "creator_id": "usr_2a3b4c5d"
}

Usage Logging

{
  "url": "https://example.com/article.html",
  "license_version_id": 463781,
  "tokens": 732,
  "stage": "infer",
  "distribution": "public",
  "ai_company": "openai",
  "model": "gpt-4",
  "verbatim": false,
  "audience": "up_to_100k"
}

{
  "usage_id": "use_9f8e7d6c5b4a",
  "charge": 0.10995,
  "tokens": 732,
  "price_per_1k": 0.15,
  "multiplier": 1.0,
  "creator_earnings": 0.10995,
  "platform_fee": 0.010995,
  "timestamp": "2025-09-29T15:30:00Z",
  "hmac_verified": true
}

HMAC Verification

HMAC signatures ensure usage logs cannot be tampered with. This creates cryptographic proof of AI usage for legal enforcement.

Generating HMAC Signature

# Python example
import hmac
import hashlib
import json
import time

def generate_hmac(payload, secret_key):
    timestamp = str(int(time.time()))
    message = f"{timestamp}.{json.dumps(payload, separators=(',', ':'))}"

    signature = hmac.new(
        secret_key.encode(),
        message.encode(),
        hashlib.sha256
    ).hexdigest()

    return {
        'signature': f"sha256={signature}",
        'timestamp': timestamp
    }

# Usage
payload = {
    "url": "https://example.com/article.html",
    "tokens": 732,
    "stage": "infer"
}

hmac_data = generate_hmac(payload, "your_secret_key")
headers = {
    'X-HMAC-Signature': hmac_data['signature'],
    'X-Timestamp': hmac_data['timestamp']
}

Signature Components

1. Timestamp: Unix timestamp of request
2. Payload: JSON-serialized request body
3. Secret Key: Your API secret key
4. Algorithm: HMAC-SHA256

Verification Process

The server verifies signatures by:

1. Checking timestamp is within 5 minutes
2. Recreating signature with stored secret
3. Comparing signatures for exact match
4. Rejecting if verification fails

Error Handling

The API uses standard HTTP status codes and returns detailed error messages.

Status Codes

Error Response Format

{
  "error": {
    "code": "INVALID_LICENSE",
    "message": "No valid license found for the specified URL",
    "details": {
      "url": "https://example.com/page.html",
      "checked": ["meta_tags", "ai_txt", "homepage"],
      "suggestion": "Add license meta tags to your HTML"
    }
  },
  "request_id": "req_a1b2c3d4e5"
}

Common Error Codes

• INVALID_API_KEY - API key is invalid or expired
• INSUFFICIENT_PERMISSIONS - API key lacks required scopes
• INVALID_LICENSE - No valid license found
• HMAC_VERIFICATION_FAILED - HMAC signature invalid
• RATE_LIMIT_EXCEEDED - Too many requests
• INVALID_PARAMETERS - Request parameters invalid

Rate Limits

API rate limits ensure fair usage and system stability.

Rate Limit Headers

Every response includes rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1698765432

Handling Rate Limits

1. Check X-RateLimit-Remaining header
2. If approaching limit, reduce request frequency
3. When limited, wait until X-RateLimit-Reset timestamp
4. Implement exponential backoff for retries

Webhooks (Coming Soon)

Webhooks will provide real-time notifications for usage events and payments.

Planned Webhook Events

• usage.logged - New usage event recorded
• payment.completed - Payment processed
• license.updated - License terms changed
• threshold.reached - Usage threshold met

Webhook Security

Webhooks will be signed with HMAC-SHA256 for verification.

Model Context Protocol (MCP)

MCP provides standardized integration for AI models to discover and respect content licenses.

MCP Endpoints

MCP Integration Example

# MCP Tool Integration
from mcp import Tool, Resource

class CopyrightLicenseChecker(Tool):
    name = "copyright_license_checker"
    description = "Check content licensing before use"

    async def run(self, url: str) -> dict:
        response = await self.http_client.post(
            "https://ledger.aposema.com/v1/mcp/discover",
            json={"urls": [url]},
            headers={"Authorization": f"Bearer {self.api_key}"}
        )
        return response.json()

# Register with MCP server
mcp_server.register_tool(CopyrightLicenseChecker())

Testing & Sandbox

Test your integration without affecting production data.

Sandbox Environment

https://sandbox-api.aposema.com/v1

Test Domains

• test-allow.aposema.com - Always returns allow license
• test-deny.aposema.com - Always returns deny
• test-paid.aposema.com - Returns paid license ($0.15)
• test-stages.aposema.com - Different prices per stage

Test API Keys

Use these keys in sandbox for testing:

// Read-only test key
Bearer test_pk_readonly_a1b2c3d4e5f6

// Full access test key
Bearer test_sk_full_z9y8x7w6v5u4t3s2