Agent API Documentation

Build AI agents that access premium content through Tollio

Quick Start

1

Sign Up & Get API Key

Create an account, subscribe to a plan, and generate your API key from the Account page.

2

Discover Content

Send a HEAD request to check if content is Tollio-enabled (free, no credits consumed).

3

Request Access Token

Call our authorization endpoint to get a single-use access token (spends credits).

4

Retrieve Content

Use the access token to fetch content directly from the publisher (free, already paid).

How It Works

Your Agent
→
Publisher Site
HEAD request (free)
Discovers headers: content_id, tier, license_id
Your Agent
→
Tollio
POST /api/v1/agent/retrieve/authorize
Receives: access_token, content_url (credits spent)
Your Agent
→
Publisher Site
GET /agentthreshold/content/{id}/
Receives: title, content_markdown, metadata (free)

API Reference

GET /api/v1/agent/subscription/status

Check your current subscription status and remaining credits.

Authentication

Authorization: Bearer agnt_your_api_key_here

Response (200 OK)

{
  "org_name": "My Organization",
  "plan": "Professional",
  "status": "active",
  "usage_count": 45,
  "monthly_limit": 1000,
  "remaining_credits": 955,
  "usage_percentage": 4.5,
  "period_start": "2026-05-01T00:00:00Z",
  "period_end": "2026-06-01T00:00:00Z",
  "days_until_renewal": 10
}
POST /api/v1/agent/retrieve/authorize

⚠️ This endpoint spends credits from your subscription

Request an access token to retrieve content. This deducts credits from your subscription based on the content tier.

Authentication

Authorization: Bearer agnt_your_api_key_here

Request Body

{
  "url": "https://publisher.com/article/123",
  "content_id": "article_123",
  "domain": "publisher.com",
  "tier": 3
}

Parameters

Field Type Description
url string Full URL of the content
content_id string Content identifier from discovery headers
domain string Publisher domain from discovery headers
tier integer Pricing tier from discovery headers

Response (201 Created)

{
  "access_token": "at_access_xyz789...",
  "retrieval_id": "ret_abc123",
  "content_url": "https://publisher.com/agentthreshold/content/article_123/",
  "expires_at": "2026-05-22T01:05:00Z",
  "credits_consumed": 3,
  "remaining_credits": 997,
  "license": {
    "summary": "Standard usage allowed",
    "internal_analysis": true,
    "summarisation": true,
    "short_quotes": true,
    "redistribution": false,
    "model_training": false,
    "cache_ttl_seconds": 86400
  }
}

Error Responses

402 Payment Required

Insufficient credits remaining in your subscription

400 Bad Request

Invalid tier or missing required fields

410 Gone

Previous token for this content has expired

Discovery Protocol

Before requesting an access token, discover if content is Tollio-enabled by sending a HEAD request to the content URL.

Request

HEAD https://publisher.com/article/123

Response Headers

X-AgentThreshold: enabled
X-AgentThreshold-Version: 1
X-AgentThreshold-Domain: publisher.com
X-AgentThreshold-Content-Id: article_123
X-AgentThreshold-Tier: 3
X-AgentThreshold-License-Id: uuid-here
X-AgentThreshold-Access-Mode: require_payment

Important Notes

  • Discovery HEAD requests are always free - no credits consumed
  • Check X-AgentThreshold header is "enabled"
  • Extract content_id, domain, and tier for authorization
  • Tier number indicates how many credits will be consumed

Content Retrieval

After receiving an access token, fetch the content directly from the publisher using the content_url provided in the authorization response.

Request

GET https://publisher.com/agentthreshold/content/article_123/
Authorization: Bearer at_access_xyz789...

Response (200 OK)

{
  "content_id": "article_123",
  "canonical_url": "https://publisher.com/article/123",
  "title": "How to Build AI Agents",
  "author": "Jane Doe",
  "published_at": "2026-05-01T12:00:00Z",
  "content_markdown": "# Full article content here...",
  "metadata": {
    "word_count": 1500,
    "reading_time": "7 minutes",
    "tags": ["AI", "Agents", "Technology"]
  }
}

Important: Content retrieval is free - credits were already consumed when you requested the access token. Tokens expire in 5 minutes, so use them promptly.

Code Examples

Python Example

import requests

class AgentThresholdClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://tollio.ai"

    def discover_content(self, url):
        """Check if content is AgentThreshold-enabled (FREE)."""
        response = requests.head(url)

        if response.headers.get('X-AgentThreshold') != 'enabled':
            return None

        return {
            'content_id': response.headers.get('X-AgentThreshold-Content-Id'),
            'domain': response.headers.get('X-AgentThreshold-Domain'),
            'tier': int(response.headers.get('X-AgentThreshold-Tier')),
            'license_id': response.headers.get('X-AgentThreshold-License-Id'),
        }

    def authorize_retrieval(self, url, content_id, domain, tier):
        """Request access token (SPENDS CREDITS)."""
        response = requests.post(
            f'{self.base_url}/api/v1/agent/retrieve/authorize',
            headers={'Authorization': f'Bearer {self.api_key}'},
            json={
                'url': url,
                'content_id': content_id,
                'domain': domain,
                'tier': tier
            }
        )
        return response.json()

    def fetch_content(self, content_url, access_token):
        """Fetch content from publisher (FREE - already paid)."""
        response = requests.get(
            content_url,
            headers={'Authorization': f'Bearer {access_token}'}
        )
        return response.json()

    def retrieve(self, url):
        """Complete workflow: discover → authorize → fetch."""
        # Step 1: Discover (free)
        metadata = self.discover_content(url)
        if not metadata:
            raise Exception("Content not AgentThreshold-enabled")

        # Step 2: Authorize (spends credits)
        auth = self.authorize_retrieval(
            url,
            metadata['content_id'],
            metadata['domain'],
            metadata['tier']
        )

        # Step 3: Fetch content (free)
        content = self.fetch_content(
            auth['content_url'],
            auth['access_token']
        )

        return content

# Usage
client = AgentThresholdClient(api_key='agnt_your_key_here')
content = client.retrieve('https://publisher.com/article/123')
print(content['title'])
print(content['content_markdown'])

Best Practices

✅ Always Check Discovery First

Send a HEAD request before authorizing to avoid wasting credits on non-enabled content.

✅ Respect License Terms

Check the license object in the authorization response and comply with usage restrictions.

✅ Monitor Your Credits

Regularly check your subscription status to avoid hitting usage limits.

✅ Use Tokens Promptly

Access tokens expire in 5 minutes. Fetch content immediately after authorization.

✅ Cache Content Appropriately

Respect the cache_ttl_seconds in the license to avoid duplicate retrievals.

❌ Never Share Your API Key

API keys are like passwords. Never commit them to version control or share them publicly.

❌ Don't Give API Keys to Publishers

Use the OAuth-style flow - only share single-use access tokens with publishers, never your API key.

Rate Limits & Quotas

Operation Limit Notes
Discovery (HEAD) Unlimited Always free, no credits consumed
Authorization Monthly plan limit Based on subscription tier
Content Fetch 1 per token Tokens are single-use
API Requests 100 req/min Per API key

Support

Need help integrating Tollio into your agent?