How to Use the Spyglasses API

Spyglasses provides an OpenAPI-compatible REST API that allows you to programmatically access your analytics data. This is useful for building custom integrations, dashboards, or automating workflows.

Overview

The Spyglasses API uses API key authentication. You can access analytics data, AI visibility rankings, historical metrics, publisher and placement scoring, and coverage tracking through simple HTTP requests.

There are two kinds of key, both sent in the same x-api-key header:

• Property API key — reads one property's analytics and metrics. Covered below.
• Organization API key — authorizes everything under /api/v1/: AIVPS publisher scoring, PQS placement scoring, and coverage group ingestion. Generate it under Organization Settings → API Key.

They are not interchangeable. See Authentication for which endpoints take which, and Automating Coverage Tracking for the Zapier/n8n workflow that feeds placements into a coverage group.

Getting Started

1. Find Your API Key

Your API key is located in your property settings:

1. Navigate to your Spyglasses dashboard
2. Select your property from the sidebar
3. Go to Settings
4. Find the API Key section
5. Click the copy button to copy your API key

Your API key looks like: sg_XXXXXXXX-XXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXX

2. Explore the API Documentation

Before integrating, we recommend exploring the interactive API documentation:

1. Visit the External API Reference page
2. Browse available endpoints
3. Test endpoints directly in the browser using your API key

3. Make Your First Request

Test your API key by fetching your property details:

curl -X GET "https://spyglasses.io/api/me" \
  -H "x-api-key: YOUR_API_KEY"

This returns your property information including the propertyId you'll need for other API calls:

{
  "propertyId": "cm9ovvnnc0001wjubh0en0cpe",
  "domain": "example.com",
  "companyName": "Example Company",
  "apiKey": "sg_XXXX...",
  "verified": true,
  "verifiedAt": "2025-01-01T00:00:00.000Z",
  "blockAiModelTrainers": false,
  "customBlocks": [],
  "customAllows": []
}

Authentication

All API requests must include your API key in the x-api-key header:

curl -X GET "https://spyglasses.io/api/endpoint" \
  -H "x-api-key: YOUR_API_KEY"

Available Endpoints

Not all API endpoints documented are available for use with an API key. If you get an error using an endpoint, confirm it's part of the list of externally-accessible endpoints. See the External API Endpoints page for a complete list of API-accessible endpoints.

Error Handling

The API returns standard HTTP status codes:

Error responses include a JSON body with details:

{
  "error": "Description of what went wrong"
}

Need Help?

• Check the External API Reference for endpoint details
• Contact us at support@spyglasses.io