Skip to content

API Access Guide

This document explains how to securely access the ZoneFeeds APIs using an API key. It covers authentication, request structure, pagination behavior, response formats, and access related best practices. Detailed endpoint definitions and parameter specifications are documented separately in API Reference.

1. Prerequisites

To access the ZoneFeeds API, you must have:

  • An approved ZoneFeeds user account with an active subscription
  • An active API key associated with your account
  • Network access to the ZoneFeeds API endpoints

How to get your API key:

  1. Account Registration – Create a new ZoneFeeds account via the registration page at https://zonefeeds.com
  2. Account Approval – After submission, your account will be approved by an administrator
  3. Subscription Activated – Upon approval, a 7-day trial subscription is created automatically
  4. API Key Issued – A default API key is generated and sent via email along with your subscription details

Account registration, approval, and API key generation are described in Register Account

2. Base URL

All API requests use the following base URL:

https://zonefeeds.com/api

Endpoint paths are appended to this base URL.

3. Authentication

All protected API endpoints require authentication via an API key.

Authorization Header

Include the API key in every request using the Bearer token format:

Authorization: Bearer <API_KEY>

Requests without a valid API key will be rejected with 401 Unauthorized.

If your subscription has expired, API requests will receive 403 Forbidden with a structured error indicating the subscription status and a URL to renew.

Subscription Requirement

In addition to a valid API key, your account must have an active subscription. If your subscription has expired, API requests will be rejected with 403 Forbidden and a message indicating that your subscription has expired.

4. API Key Management

  • API keys are issued after account approval
  • A default API key is generated automatically upon approval
  • Keys are bound to a specific user account
  • API key default validity matches your subscription tier:
    • Trial: 7 days
    • Basic: 365 days
    • Enterprise: 365 days
  • Important: API keys have their own expiry independent of your subscription. When your subscription renews, existing API keys are not automatically extended. You must generate new keys from your dashboard or API.
  • Users can generate additional keys via the API
  • Keys can be revoked by the user or by administrators

Security Recommendations

  • Never embed API keys in client side or frontend applications
  • Store keys securely using environment variables or secret managers
  • Use separate keys for development and production environments
  • Rotate keys immediately if exposure is suspected

5. Request Structure

Each API request consists of:

  • HTTP method (GET)
  • Fully qualified endpoint URL
  • Authorization header
  • Optional query parameters

Example request structure:

GET /api/v1/download/{tld}.zone
Authorization: Bearer <API_KEY>

Supported Query Parameters

Parameter Type Description
start ISO 8601 datetime Start of the time window (UTC). Required for trial users.
end ISO 8601 datetime End of the time window (UTC). Optional.
search string Domain name or keyword filter.
limit integer (1–10,000) Maximum records returned. Clamped to your tier's maximum.

Example Request:

GET https://zonefeeds.com/api/api/v1/download/com.zone?start=2025-12-20T10:30:00Z&end=2025-12-25T10:30:00Z&limit=1000&search=technology

6. Query Capabilities by Tier

Available features depend on your subscription tier:

Capability Trial Basic Enterprise
TLD-based queries Yes Yes Yes
Domain/keyword search Yes Yes Yes
Wildcard search (*) No Yes (max 5,000 records) Yes (max 5,000 records)
Browse without filter No Yes Yes
Max records per query 1,000 5,000 10,000
Historical data window 7 days 30 days 180 days
Punycode/IDN search Yes Yes Yes

Trial users must provide a start date with every request (a search term alone is not sufficient).

Refer to API Reference for detailed parameter definitions.

7. Internationalized Domains and Punycode

ZoneFeeds APIs expect Punycode encoded values when querying internationalized domains or TLDs.

  • Unicode domains must be converted to Punycode before submission
  • Both TLD and domain fields accept Punycode values
  • The platform decodes and normalizes Unicode internally for analysis

This enables detection of multilingual phishing and homograph abuse.

8. Pagination and Result Navigation

ZoneFeeds uses cursor based pagination to ensure consistent and high performance queries.

Pagination Fields

Field Description
pit Elasticsearch Point In Time identifier
after Base64 encoded cursor for the next page
limit Number of records to return (clamped to tier maximum)

Pagination Flow

  1. The initial request returns a pit value
  2. If additional records exist, a next_cursor value is returned
  3. To fetch the next page, include:
  4. pit=<PIT_ID>
  5. after=<CURSOR_BASE64>
  6. Continue until no next_cursor is returned

Example:

If your initial request was:

GET https://zonefeeds.com/api/api/v1/download/com.zone?start=2025-12-20T10:30:00Z&end=2025-12-25T10:30:00Z&limit=1000&search=technology

and the response returned:

{
  "pit": "w8abBAYN...",
  "results": [...],
  "next_cursor": "WzEyODg2XQ=="
}

Your next page request must include the original query parameters along with the pagination values:

GET https://zonefeeds.com/api/api/v1/download/com.zone?start=2025-12-20T10:30:00Z&end=2025-12-25T10:30:00Z&limit=1000&search=technology&after=WzEyODg2XQ==&pit=w8abBAYN...

Note: Omitting the original parameters will result in incorrect or inconsistent page results.

Important Notes

  • PIT values remain valid for 2 minutes
  • If a PIT expires, a 410 Gone error is returned — start a new query from page 1
  • Cursor continuation requests are not counted toward your query quota

9. JSON Response Format

All API responses are returned in JSON format.

Common Response Fields

Field Description
results Array of domain observation objects. Each object represents a single domain state observation.
domain Fully qualified domain name (FQDN) observed in the registry zone dataset (e.g., example.com).
status Domain presence state — active (present in zone) or inactive (no longer present).
data DNS record value associated with the domain (e.g., ns1.example.com.).
timestamp Time the domain state was observed. Not the domain registration or expiry date.
pit Point-In-Time identifier for consistent pagination. Valid for 2 minutes.
next_cursor Encoded cursor for the next page. Absent when no more results exist.

10. Access Errors and Status Codes

Status Code Meaning Detail Format Description
400 Bad Request String Invalid parameters, search pattern, or future dates
401 Unauthorized String Invalid, missing, or expired API key
403 Forbidden String or Object Subscription expired, feature not available on tier, or data window exceeded
404 Not Found String No data available for the selected timeframe or no domains found
410 Gone String Pagination session (PIT) expired — restart from page 1
429 Too Many Requests Object Query quota exceeded — includes message, limit, used, and resets_at fields

Error Response Format

Errors return a JSON object with a detail field. The detail value is either a string or an object:

String detail (most errors):

{
  "detail": "Your Trial subscription has expired. Please upgrade to continue."
}

Subscription expired (structured):

{
  "detail": {
    "error": "subscription_expired",
    "message": "Your Basic subscription has expired. Please renew to continue.",
    "renew_url": "/pricing"
  }
}

Object detail (quota and data window errors):

{
  "detail": {
    "message": "Query limit exceeded. Your trial plan allows 100 queries per 7 days. Resets on Apr 02, 2026.",
    "tier": "trial",
    "limit": 100,
    "used": 100,
    "resets_at": "2026-04-02T12:00:00+00:00"
  }
}

11. Rate Limiting and Quotas

API usage is limited based on your subscription tier. Quotas reset monthly, aligned to the day of the month you subscribed.

Tier Query Quota Reset Period
Trial 100 queries 7-day trial period
Basic 1,000 queries Monthly
Enterprise 10,000 queries Monthly
  • Cursor-based pagination requests (using pit and after) are not counted toward your quota
  • When your quota is exceeded, the API returns 429 with the reset date
  • Implement retry logic with exponential backoff for production integrations

See Subscription for full plan details.

12. Best Practices

  • Validate request inputs before sending
  • Use pagination for large result sets — cursor requests don't count toward quota
  • Monitor API responses and handle errors gracefully
  • Restart queries when PIT expires (410 response)
  • Check your usage dashboard to track quota consumption

13. Support

For API access issues or assistance:

  • Contact the ZoneFeeds support team at sales@zonefeeds.com
  • Use the Upgrade button in the web app to request a plan change