TollBit

https://docs.tollbit.com
Admin
TollBit is a platform that enables publishers and content owners to monitor, manage, and monetize AI...
Tokens:73,888
Snippets:568
Trust Score:9.6
Update:1 day ago
Show doc for...
Tokens:
Raw
### Get Rate Response Example

Source: https://docs.tollbit.com/docs/rates

Example JSON response from the Get Rate endpoint. Returns an array of rate options, each with a license and price. The license includes an id, licensePath, licenseType, and permissions. The price includes currency and priceMicros.

```json
[
  {
    "license": {
      "id": "nl1sqiauvujk8i6u507wy2mi",
      "licensePath": "<license_url>",
      "licenseType": "ON_DEMAND_LICENSE",
      "permissions": [
        { "name": "PARTIAL_USE" }
      ]
    },
    "price": {
      "currency": "USD",
      "priceMicros": 5000
    }
  },
  {
    "license": {
      "id": "rrmeq2kjsvouhda4ud28uykl",
      "licensePath": "<license_url>",
      "licenseType": "ON_DEMAND_FULL_USE_LICENSE",
      "permissions": [
        { "name": "FULL_USE" },
        { "name": "PARTIAL_USE" }
      ]
    },
    "price": {
      "currency": "USD",
      "priceMicros": 10000
    }
  }
]
```

--------------------------------

### Get Rates with Python SDK

Source: https://docs.tollbit.com/docs/search-to-content

Python example using the tollbit SDK to create a use_content client and fetch rates for a selected URL from search results. Requires TOLLBIT_ORG_API_KEY and TOLLBIT_USER_AGENT environment variables (or placeholders). The response contains rate objects with price and license details.

```python
from tollbit import use_content
import os

api_key = os.getenv("TOLLBIT_ORG_API_KEY", "YOUR_API_KEY_HERE")
user_agent = os.getenv("TOLLBIT_USER_AGENT", "tollbit-python-sdk-example/0.1.0")

# Create a use_content client
content_client = use_content.create_client(secret_key=api_key, user_agent=user_agent)

# Get rates for a specific URL (from your search results)
selected_url = results.items[0].url  # Using the first result from Step 1
rate_info = content_client.get_rate(url=selected_url)

# Display rate information
print(f"\nFound {len(rate_info)} rate(s) for {selected_url}:")
for rate in rate_info:
    print(f"\n  Price: {rate.price.price_micros / 1_000_000:.2f} {rate.price.currency}")
    print(f"  License ID: {rate.license.id}")
    print(f"  License Type: {rate.license.license_type}")
    print(f"  License Path: {rate.license.license_path}")
    print(f"  Permissions: {[p.name for p in rate.license.permissions]}")
```

--------------------------------

### Bulk Get Rate Example Request (curl)

Source: https://docs.tollbit.com/docs/rates

Example curl command to call the Bulk Get Rate endpoint. Replace YOUR_API_KEY_HERE with your actual API key.

```bash
curl --location 'https://gateway.tollbit.com/dev/v2/rates/batch' \
  --header 'TollbitKey: YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "urls": [
      "https://example.com/article-1",
      "https://example.com/article-2"
    ]
  }'
```

--------------------------------

### List Content Catalog Example Request

Source: https://docs.tollbit.com/docs/content

Example cURL request to list the content catalog for example.com. Requires an API key in the TollbitKey header.

```bash
curl --location 'https://gateway.tollbit.com/dev/v2/content/example.com/catalog/list' \
  --header 'TollbitKey: YOUR_API_KEY_HERE'
```

--------------------------------

### Install tollbit-python-sdk

Source: https://docs.tollbit.com/docs/search-to-content

Installs the Tollbit Python SDK via pip. This is a prerequisite for using the Python SDK workflow.

```bash
pip install tollbit-python-sdk
```

--------------------------------

### Python: Retrieve sanctioned content with get_sanctioned_content

Source: https://docs.tollbit.com/docs/search-to-content

Use the Python SDK to retrieve content in a single call. It automatically handles token acquisition. Specify the URL, max price in micros, currency, and license type. Optionally get rates first to determine pricing. The example shows how to access content, metadata, and rate information, and how to request HTML format.

```python
from tollbit import use_content
from tollbit import licenses
from tollbit import currencies
from tollbit import content_formats
import os

api_key = os.getenv("TOLLBIT_ORG_API_KEY", "YOUR_API_KEY_HERE")
user_agent = os.getenv("TOLLBIT_USER_AGENT", "tollbit-python-sdk-example/0.1.0")

content_client = use_content.create_client(secret_key=api_key, user_agent=user_agent)

# Select a URL from your search results (from Step 1)
selected_url = results.items[0].url

# Optionally get rates first to determine pricing (from Step 2)
rate_info = content_client.get_rate(url=selected_url)
if rate_info:
    selected_rate = rate_info[0]
    max_price = selected_rate.price.price_micros
else:
    max_price = 11000000  # 11.00 USD in micros

# Get content in Markdown format (default)
# This automatically obtains a token and retrieves the content
data = content_client.get_sanctioned_content(
    url=selected_url,
    max_price_micros=max_price,
    currency=currencies.USD,
    license_type=licenses.types.ON_DEMAND_LICENSE,
)

# Access the content
print("Content:")
print(f"Header: {data.content.header}")
print(f"Body: {data.content.body}")
print(f"Footer: {data.content.footer}")

# Access metadata
print("\nMetadata:")
print(f"Title: {data.metadata.title}")
print(f"Description: {data.metadata.description}")
print(f"Author: {data.metadata.author}")
print(f"Published: {data.metadata.published}")
print(f"Modified: {data.metadata.modified}")

# Access rate information (if available)
if data.rate:
    print(f"\nRate: {data.rate.price.price_micros / 1_000_000:.2f} {data.rate.price.currency}")

# Get content in HTML format
data_html = content_client.get_sanctioned_content(
    url=selected_url,
    max_price_micros=11000000,
    currency=currencies.USD,
    license_type=licenses.types.ON_DEMAND_LICENSE,
    format=content_formats.HTML,
)
```

--------------------------------

### Bulk Get Rate Response Example

Source: https://docs.tollbit.com/docs/rates

Example JSON response from the Bulk Get Rate endpoint. It returns an array of objects, each containing a url and a rates array with price and license details.

```json
[
  {
    "url": "https://example.com/article-1",
    "rates": [
      {
        "price": {
          "priceMicros": 5000,
          "currency": "USD"
        },
        "license": {
          "cuid": "ji73lwbqjnhfgpu1bk3sjzj1",
          "licenseType": "ON_DEMAND_LICENSE",
          "licensePath": "<license_url>",
          "permissions": [{ "name": "PARTIAL_USE" }]
        }
      },
      {
        "price": {
          "priceMicros": 10000,
          "currency": "USD"
        },
        "license": {
          "cuid": "ec1lhwillyl6i3x4gnb4a6gt",
          "licenseType": "ON_DEMAND_FULL_USE_LICENSE",
          "licensePath": "<license_url>",
          "permissions": [
            { "name": "FULL_USE" },
            { "name": "PARTIAL_USE" }
          ]
        }
      }
    ]
  },
  {
    "url": "https://example.com/article-2",
    "rates": [...]
  }
]
```

--------------------------------

### Generate Indexing Token - Example Request (Bash)

Source: https://docs.tollbit.com/docs/tokens

Example curl command to generate an indexing token. Replace YOUR_API_KEY_HERE with your actual API key and provide the target URL and user agent.

```bash
curl https://gateway.tollbit.com/dev/v2/tokens/crawl \
  -H "Content-Type: application/json" \
  -H "TollbitKey: YOUR_API_KEY_HERE" \
  -d '{"url": "https://example.com/article", "userAgent": "my-agent/1.0"}'
```

--------------------------------

### Get Rate Example Request (curl)

Source: https://docs.tollbit.com/docs/rates

Example curl command to call the Get Rate endpoint. The content URL must be URL-encoded in the path. Replace YOUR_API_KEY_HERE with your actual API key.

```bash
# URL-encode the content URL when using it in the path
curl -G "https://gateway.tollbit.com/dev/v2/rates/https%3A%2F%2Fexample.com%2Farticle" \
  --header "TollbitKey: YOUR_API_KEY_HERE"
```

--------------------------------

### Generate Content Token - Example Response (Error)

Source: https://docs.tollbit.com/docs/tokens

Example error response with a 400 status, including details about the failure.

```json
{
  "detail": "The license...",
  "instance": "/dev/v2/tokens/content",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
```

--------------------------------

### Get Content Example Request (curl)

Source: https://docs.tollbit.com/docs/content

Example curl command to request content. Uses the TollbitToken header with a one-time token and a User-Agent containing your AgentID. The content_path is URL-encoded.

```bash
curl --location 'https://gateway.tollbit.com/dev/v2/content/https%3A%2F%2Fexample.com%2Farticle' \
  --header 'TollbitToken: eyJhbGciOiJF...' \
  --header 'User-Agent: my-agent/1.0'
```

--------------------------------

### Generate Indexing Token - Example Response (Error)

Source: https://docs.tollbit.com/docs/tokens

Example error response with status 400 and details.

```json
{
  "detail": "The license...",
  "instance": "/dev/v2/tokens/crawl",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
```

--------------------------------

### Generate Content Token - Example Request (Bash)

Source: https://docs.tollbit.com/docs/tokens

Example curl command to generate a content token. Replace YOUR_API_KEY_HERE with your actual API key. The request body includes the URL, user agent, max price, currency, and license type.

```bash
curl https://gateway.tollbit.com/dev/v2/tokens/content \
  -H "Content-Type: application/json" \
  -H "TollbitKey: YOUR_API_KEY_HERE" \
  -d '{"url": "https://example.com/article", "userAgent": "my-agent/1.0", "maxPriceMicros": 11000000, "currency": "USD", "licenseType": "ON_DEMAND_LICENSE"}'
```

--------------------------------

### Generate Content Token - Example Response (Success)

Source: https://docs.tollbit.com/docs/tokens

Example successful response containing the JWT token that can be used for content requests.

```json
{
  "token": "eyJhbGciOiJFUzI1..."
}
```

--------------------------------

### Verify setup with curl using GPTBot user agent

Source: https://docs.tollbit.com/docs/akamai

Command to test the Forward Rewrite setup by requesting a page with a bot user agent. Confirm the response body contains the agent version of the page.

```bash
curl -A "GPTBot" https://example.com/some-article
```

--------------------------------

### Example webhook delivery record

Source: https://docs.tollbit.com/docs/webhooks

Example of a single item in the Items array. Shows fields such as subscriptionId, contentUrl, deliveryUrl, eventType, lastAttempt, lastStatus, and numAttempts.

```json
{
  "subscriptionId": "sub_abc123",
  "contentUrl": "https://example.com/article/123",
  "deliveryUrl": "https://your-app.com/webhooks/tollbit",
  "eventType": "CREATE",
  "lastAttempt": "2025-09-30T23:08:40.620435262Z",
  "lastStatus": 200,
  "numAttempts": 1
}
```

--------------------------------

### JSON: Token response example

Source: https://docs.tollbit.com/docs/search-to-content

Shows the JSON structure returned by the token endpoint. Save the token value for the next step.

```json
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

--------------------------------

### Search with Additional Parameters using curl (Bash)

Source: https://docs.tollbit.com/docs/search-to-content

Shows how to customize searches with size, properties, readyToLicense, and next-token parameters using curl. Each command is a separate example.

```bash
# Search with size limit
curl --location 'https://gateway.tollbit.com/dev/v2/search?q=python%20tutorial&size=5' \
--header 'TollbitKey: <key>'

# Search on specific properties (filter to only these domains)
curl --location 'https://gateway.tollbit.com/dev/v2/search?q=tutorial&size=10&properties=example.com,tutorial.com' \
--header 'TollbitKey: <key>'

# Search only properties that can be licensed programmatically
curl --location 'https://gateway.tollbit.com/dev/v2/search?q=tutorial&readyToLicense=true' \
--header 'TollbitKey: <key>'

# Pagination - get next page
curl --location 'https://gateway.tollbit.com/dev/v2/search?q=DIY%20projects&next-token=<next_token_from_previous_response>' \
--header 'TollbitKey: <key>'
```

--------------------------------

### Search with Additional Parameters using Python SDK

Source: https://docs.tollbit.com/docs/search-to-content

Shows how to customize searches with size, properties, and next_token using the Python SDK. The pagination example uses the next_token from a previous response.

```python
# Search with size limit
results = search_client.search(q="python tutorial", size=5)

# Search on specific properties (filter to only these domains)
results = search_client.search(
    q="tutorial",
    size=10,
    properties=["example.com", "tutorial.com"],
)

# Pagination - get next page
if results.next_token:
    next_page = search_client.search(
        q="DIY home projects for millennials",
        next_token=results.next_token,
    )
```

--------------------------------

### GET /dev/v2/rates/{content_path}

Source: https://docs.tollbit.com/docs/rates

Get the rate(s) for a single webpage. The content path is the full URL of the intended webpage (URL-encoded when used in the path).

```APIDOC
## GET /dev/v2/rates/{content_path}

### Description
Get the rate(s) for a single webpage. The content path is the full URL of the intended webpage (URL-encoded when used in the path).

### Method
GET

### Endpoint
`/dev/v2/rates/{content_path}`

### Base URL
`https://gateway.tollbit.com`

### Authentication
Requires API key via the `TollbitKey` header.

### Parameters
#### Path Parameters
- **content_path** (string) - Required - The full URL of the intended webpage. URL-encode the URL when used in the path (e.g. `https%3A%2F%2Fexample.com%2Farticle`).

#### Request Headers
- **TollbitKey** (string) - Required - Your API key, available in the access page of the dashboard.

### Request Example
```bash
# URL-encode the content URL when using it in the path
curl -G "https://gateway.tollbit.com/dev/v2/rates/https%3A%2F%2Fexample.com%2Farticle" \
  --header "TollbitKey: YOUR_API_KEY_HERE"
```

### Response
#### Success Response (200)
The API returns an array of rate options. Each option includes a license and price.

#### Response Fields (per rate option)
- **license** (object)
  - **id** (string): License identifier.
  - **licensePath** (string): URL to view the license.
  - **licenseType** (string): One of `ON_DEMAND_LICENSE`, `ON_DEMAND_FULL_USE_LICENSE`, `CUSTOM_LICENSE`.
  - **permissions** (array): Rights granted. May include `PARTIAL_USE`, `FULL_USE`, `CITATION_REQUIRED`.
- **price** (object)
  - **priceMicros** (integer): Price in micros ($1 = 1,000,000 micros).
  - **currency** (string): Currency code (e.g. `USD`).

#### Response Example
```json
[
  {
    "license": {
      "id": "nl1sqiauvujk8i6u507wy2mi",
      "licensePath": "<license_url>",
      "licenseType": "ON_DEMAND_LICENSE",
      "permissions": [
        { "name": "PARTIAL_USE" }
      ]
    },
    "price": {
      "currency": "USD",
      "priceMicros": 5000
    }
  },
  {
    "license": {
      "id": "rrmeq2kjsvouhda4ud28uykl",
      "licensePath": "<license_url>",
      "licenseType": "ON_DEMAND_FULL_USE_LICENSE",
      "permissions": [
        { "name": "FULL_USE" },
        { "name": "PARTIAL_USE" }
      ]
    },
    "price": {
      "currency": "USD",
      "priceMicros": 10000
    }
  }
]
```
```

--------------------------------

### Parse Rates in Python

Source: https://docs.tollbit.com/docs/search-to-content

Python example showing how to access the first rate object from the rate_info list and print its price in dollars and license type. Assumes rate_info is the result from content_client.get_rate().

```python
# Rates are already parsed into objects
if rate_info:
    first_rate = rate_info[0]
    price_usd = first_rate.price.price_micros / 1_000_000
    print(f"Price: {price_usd:.2f} {first_rate.price.currency}")
    print(f"License Type: {first_rate.license.license_type}")
```

--------------------------------

### GET /dev/v1/webhook/history

Source: https://docs.tollbit.com/reference/getwebhookhistory

Get the history of webhooks within an optional lookback window, including specific content URLs and last attempted delivery time and status.

```APIDOC
## GET /dev/v1/webhook/history

### Description
Get the history of webhooks within an optional lookback window, including specific content URLs and last attempted delivery time and status.

### Method
GET

### Endpoint
https://gateway.tollbit.com/dev/v1/webhook/history

### Parameters
#### Query Parameters
- **next-token** (string) - Optional - Optional pagination token. Response includes a token to retrieve the next page if available.
- **size** (integer) - Optional - Number of items per page. Default 25. Max 1000.
- **days-ago** (integer) - Optional - Number of days back from current date to retrieve webhook history.

### Response
#### Success Response (200)
Success

```

--------------------------------

### Self Report Usage cURL Example

Source: https://docs.tollbit.com/docs/content

Example cURL command to self-report usage. Replace YOUR_API_KEY_HERE with your API key and adjust the idempotencyId and usage entries as needed.

```bash
curl --location 'https://gateway.tollbit.com/tollbit/dev/v2/transactions/selfReport' \
  --header 'UserAgent: my-agent/1.0' \
  --header 'TollbitKey: YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --data '{
    "idempotencyId": "1234",
    "usage": [
      {
        "url": "https://example.com/article",
        "timesUsed": 2,
        "licenseType": "ON_DEMAND_LICENSE"
      }
    ]
  }'
```

--------------------------------

### Bulk Get Rate Endpoint

Source: https://docs.tollbit.com/docs/rates

The endpoint for the Bulk Get Rate API. It requires an API key via the TollbitKey header and a JSON body with a list of URLs.

```http
POST /dev/v2/rates/batch
```

--------------------------------

### Get Content Response Format

Source: https://docs.tollbit.com/docs/content

The JSON response structure returned by the Get Content endpoint. Contains content sections (header, body, footer), metadata, and rate information.

```json
{
  "content": {
    "header": "...",
    "body": "...",
    "footer": "..."
  },
  "metadata": {
    "author": "string",
    "description": "string",
    "imageUrl": "string",
    "modified": "string",
    "published": "string",
    "title": "string"
  },
  "rate": {
    "license": { "id": "string", "licensePath": "string", "licenseType": "string", "permissions": [] },
    "price": { "currency": "string", "priceMicros": 0 }
  }
}
```

--------------------------------

### Pagination - First Response

Source: https://docs.tollbit.com/docs/licensed-search

Example response from the first paginated request, showing the nextToken field used to fetch the next page.

```json
{
  "nextToken": "MToyMA==",
  "items": [...]
}
```

--------------------------------

### Example webhook payload (JSON)

Source: https://docs.tollbit.com/docs/webhooks

Example JSON payload for a TollBit webhook delivery. Contains fields: sourceCuid, sourceHost, contentUrl, timestamp, and notificationType. The notificationType is either CREATED or UPDATED.

```json
{
  "sourceCuid": "rd4mezz10lifxlk90d9nd38p",
  "sourceHost": "pioneervalleygazette.com",
  "contentUrl": "https://pioneervalleygazette.com/article/bubble-fairy",
  "timestamp": "2025-09-30T23:08:40.620435262Z",
  "notificationType": "CREATED"
}
```
Tokens:
Raw