Spyse Getting Started: API Access and First Request (2026)

Getting started overview

Getting started with Spyse involves a sequence of standard steps common to many API platforms. Users first register for an account on the official Spyse website. Following account creation, an API key must be generated within the user dashboard. This key serves as the authentication credential for all programmatic interactions with the Spyse API. The process culminates in making an initial API request, typically using a tool like curl or a dedicated SDK, to confirm successful setup and access to data. Spyse offers a free tier with limited daily requests, allowing new users to explore the platform's capabilities before committing to a paid plan.

The Spyse API provides access to a range of cybersecurity datasets, including information on domains, IPs, certificates, and vulnerabilities, which can support activities such as attack surface management and threat intelligence gathering. The platform also offers a dedicated documentation portal to assist developers with integration and usage.

Create an account and get keys

To begin using the Spyse API, establishing a user account is the first prerequisite. Navigate to the Spyse registration page and follow the prompts to create a new account. This typically involves providing an email address, setting a password, and agreeing to the terms of service. Account verification, often via email, may be required to complete the registration process.

Once your account is active, log in to the Spyse dashboard. Within the dashboard, locate the section dedicated to API access or developer settings. Here, you will find an option to generate an API key. This key is a unique alphanumeric string that authenticates your requests to the Spyse API. Treat your API key as sensitive credentials, similar to a password, to prevent unauthorized access to your account and data usage. Spyse's documentation specifies that API keys are essential for all programmatic interactions, ensuring that only authorized users can query the datasets. Ensure you store this key securely, for example, using environment variables in your development environment rather than embedding it directly in code, consistent with general API key security best practices.

The API key allows Spyse to attribute API calls to your account, track usage against your plan limits (including the free tier's daily request limit), and enforce access controls. If you suspect your API key has been compromised, you should revoke it from your Spyse dashboard and generate a new one immediately.

Your first request

After obtaining your API key, you are ready to make your first request to the Spyse API. This initial call serves to confirm that your API key is correctly configured and that you can successfully connect to the Spyse service. Spyse provides a comprehensive API reference detailing available endpoints and their specific parameters. For this example, we will query a basic endpoint to retrieve information about a domain.

Using curl

The curl command-line tool is a common method for making HTTP requests and is useful for quickly testing API endpoints. Replace YOUR_API_KEY with your actual Spyse API key.

curl -X GET \
  "https://api.spyse.com/v4/domain?q=google.com" \
  -H "X-API-KEY: YOUR_API_KEY"

This command sends a GET request to the /v4/domain endpoint, querying for information related to google.com. The -H "X-API-KEY: YOUR_API_KEY" header is crucial for authenticating your request with your API key. A successful response will return a JSON object containing data about the specified domain. An example of a successful (but truncated) response might look like this:

{
  "data": [
    {
      "domain_name": "google.com",
      "alexa_rank": 1,
      "registered_date": "1997-09-15T00:00:00Z",
      "registrar": "MarkMonitor Inc.",
      "country_code": "US",
      "ip_addresses": [
        "142.250.72.14",
        "172.217.160.142"
      ],
      "whois_raw": "... (truncated for brevity) ..."
    }
  ],
  "meta": {
    "total": 1,
    "offset": 0,
    "limit": 10
  }
}

If you receive an error, such as 401 Unauthorized or 403 Forbidden, double-check that your API key is correct and properly included in the X-API-KEY header.

Using the Python SDK

Spyse provides a Python SDK to simplify integration. First, install the SDK:

pip install spyse

Then, you can make a request programmatically:

import os
from spyse import Spyse

# It's recommended to store your API key as an environment variable
api_key = os.environ.get("SPYSE_API_KEY") 

if not api_key:
    print("Error: SPYSE_API_KEY environment variable not set.")
    exit(1)

spyse = Spyse(api_key)

try:
    # Query for domain information
    domains = spyse.api.domains.search(search_params={"domain": "google.com"})
    
    if domains:
        for domain_data in domains:
            print(f"Domain: {domain_data.domain_name}")
            print(f"Alexa Rank: {domain_data.alexa_rank}")
            print(f"IP Addresses: {', '.join(domain_data.ip_addresses)}")
    else:
        print("No data found for google.com")

except Exception as e:
    print(f"An error occurred: {e}")

This Python script initializes the Spyse client with your API key and then uses the domains.search method to query for domain data. The SDK handles the underlying HTTP request and JSON parsing, returning Python objects for easier manipulation. This method is generally preferred for larger applications due to its convenience and error handling capabilities.

Common next steps

Once you have successfully made your first API request, several common next steps can help you further integrate Spyse into your workflows:

1. Explore Additional Endpoints: The Spyse API reference lists various endpoints for different data types, such as IP addresses, SSL certificates, vulnerabilities, and autonomous systems. Investigate these to understand the full scope of data available for your cybersecurity investigations or attack surface management needs.
2. Implement Error Handling: For production applications, robust error handling is crucial. Implement mechanisms to catch API errors (e.g., rate limits, invalid parameters, authentication failures) and handle them gracefully. The Spyse API will typically return HTTP status codes and JSON error messages to indicate issues.
3. Manage Rate Limits: Be aware of the rate limits associated with your Spyse plan (free or paid). Implement retry logic with exponential backoff for rate-limited responses (HTTP 429) to prevent exceeding your allowance and ensure your application remains responsive.
4. Utilize Advanced Querying: Spyse's API supports advanced search parameters, including filtering and sorting options, to refine your data retrieval. Familiarize yourself with these capabilities to obtain precisely the information you need, reducing unnecessary data transfer and processing.
5. Integrate with Security Tools: Consider integrating Spyse data with existing security information and event management (SIEM) systems, vulnerability scanners, or threat intelligence platforms to enrich your security posture and automate data collection processes.
6. Review Pricing and Upgrade: If your usage exceeds the free tier's limitations or if you require more advanced features, review the available paid plans. Spyse offers various tiers, starting at $29/month for the Starter plan, which scale with query volume and feature sets.

Troubleshooting the first call

Encountering issues during your first API call is common. Here's a guide to common problems and their solutions:

• 401 Unauthorized / 403 Forbidden:
  • Incorrect API Key: Double-check that you have copied your API key correctly from your Spyse dashboard. Even a single character mismatch will cause authentication to fail.
  • Missing API Key Header: Ensure the X-API-KEY header is present in your request and correctly formatted. For curl, this means -H "X-API-KEY: YOUR_API_KEY". For the Python SDK, ensure your SPYSE_API_KEY environment variable is set or the key is passed correctly during client initialization.
  • Expired or Revoked Key: Verify that your API key is still active in your Spyse account settings. If it was revoked or has an expiration, generate a new one.
  • Insufficient Permissions: While less common for a first call, certain endpoints might require specific plan levels or permissions. Ensure your account plan supports the requested data.
• 429 Too Many Requests:
  • Rate Limit Exceeded: This indicates you have sent too many requests within a short period, exceeding your plan's rate limit. Wait for a few moments and try again. For continuous integration, implement exponential backoff retry logic.
  • Free Tier Limits: The free tier has strict daily limits. If you hit this, you may need to wait until the next day or consider upgrading your plan.
• Network Issues:
  • Connectivity: Confirm your internet connection is stable.
  • Firewall/Proxy: If you are behind a corporate firewall or proxy, ensure it is configured to allow outbound connections to api.spyse.com on HTTPS (port 443).
• Incorrect Endpoint or Parameters:
  • Typos: Double-check the URL for the endpoint (e.g., /v4/domain) and any query parameters (e.g., q=google.com) against the Spyse API documentation.
  • Required Parameters Missing: Some endpoints require specific parameters that, if omitted, will result in an error.
• JSON Parsing Errors:
  • If your client application struggles to parse the response, ensure it's expecting JSON. Verify that the API response is indeed valid JSON using an online JSON validator if necessary.