Searchable

https://docs.searchable.com/
Admin
Searchable is an AI-powered SEO and AEO (Answer Engine Optimization) platform that helps businesses...
Tokens:27,710
Snippets:339
Trust Score:8
Update:8 months ago
Show doc for...
Tokens:
Raw
### MCP Integration Setup

Source: https://docs.searchable.com/integrations/mcp

This section details how to set up the MCP integration with Searchable, including obtaining an API key and configuring various AI assistants.

```APIDOC
## MCP Integration Setup

### Step 1: Get Your API Key

1. Navigate to **Settings** > **Workspace** > **Integrations** in your Searchable dashboard.
2. Click **Create API Key** and provide a descriptive name (e.g., "Cursor MCP").
3. Copy your API key (starts with `sea_`). Store it securely.

### Step 2: Configure Your AI Assistant

**Cursor:**
Add the following to your Cursor MCP configuration file (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "searchable": {
      "url": "https://searchable-mcp-production.searchable.workers.dev/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```
Replace `YOUR_API_KEY` with your actual API key.

**Claude Code:**
Run the following command:

```bash
claude mcp add searchable \
  --transport sse \
  --url "https://searchable-mcp-production.searchable.workers.dev/sse" \
  --header "Authorization: Bearer YOUR_API_KEY"
```
Alternatively, add to your Claude Code config (`~/.claude/claude_code_config.json`):

```json
{
  "mcpServers": {
    "searchable": {
      "url": "https://searchable-mcp-production.searchable.workers.dev/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```
Replace `YOUR_API_KEY` with your actual API key.

**Windsurf:**
Add to your Windsurf MCP configuration:

```json
{
  "mcpServers": {
    "searchable": {
      "url": "https://searchable-mcp-production.searchable.workers.dev/sse",
      "transport": "sse",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
```
Replace `YOUR_API_KEY` with your actual API key.

### Step 3: Verify Connection

Restart your AI assistant after configuration. "Searchable" should appear in your available MCP servers. Test by asking: "List my Searchable projects".
```

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

### API Key Best Practices

Source: https://docs.searchable.com/integrations/mcp

Guidelines for securely managing your API keys to protect your Searchable data.

```APIDOC
## API Key Management

### Best Practices

*   **Rotate keys regularly**: Generate new API keys periodically to enhance security.
*   **Use project-specific keys**: Create distinct API keys for different applications or use cases to isolate potential compromises.
*   **Revoke unused keys**: Remove any API keys that are no longer needed to minimize security risks.
*   **Never share keys**: Ensure each user or service has its own unique API key. Do not share keys across different entities.
```

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

### Rate Limits

Source: https://docs.searchable.com/integrations/mcp

Information on request limits to ensure fair usage and system stability.

```APIDOC
## Rate Limits

### Limits

*   **100 requests per minute** per API key.
*   Requests that exceed the rate limit will receive a **429 Too Many Requests** status code.
*   Rate limits are reset every 60 seconds.
```

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

### MCP Tools

Source: https://docs.searchable.com/integrations/mcp

The Searchable MCP provides several tools to access your project data, including listing projects and retrieving visibility summaries and details.

```APIDOC
## Available Tools

### Project Management

#### `list_projects`

**Description:** List all Searchable projects for the authenticated user.

**Returns:** Project names, domains, descriptions, and IDs.

**Example prompt:** "List all my Searchable projects"

### AI Visibility

#### `get_visibility_summary`

**Description:** Get AI visibility summary for a project.

**Returns:** Overall visibility score, mention rate, citations, and how the brand appears across AI platforms (ChatGPT, Claude, Perplexity, Gemini).

**Parameters:**

* `projectId` (string) - Required - Project ID
* `days` (integer) - Optional - Analysis period (default: 30)

**Example prompt:** "What's my visibility score for project 'example-project-id' over the last 60 days?"

#### `get_visibility_details`

**Description:** Get detailed visibility breakdown by platform.

**Returns:** Per-platform visibility rates, responses, mentions, and citations for ChatGPT, Claude, Perplexity, and Gemini.

**Parameters:**

* `projectId` (string) - Required - Project ID
* `days` (integer) - Optional - Analysis period (default: 30)

**Example prompt:** "Show me the visibility details for project 'example-project-id' across all platforms."
```

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

### Fetch Scores and Calculate Trend (JavaScript)

Source: https://docs.searchable.com/advanced/api-usage

This example shows how to fetch daily scores for a project over the last 30 days using the Searchable SDK and then calculate the score trend. It's useful for building custom monitoring dashboards.

```javascript
// Fetch daily scores
const scores = await searchable.getScores({
  projectId: 'your-project',
  dateRange: 'last30days'
});

// Display trend
const trend = calculateTrend(scores);
console.log(`Score trend: ${trend > 0 ? '↑' : '↓'} ${Math.abs(trend)}%`);
```

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

### Data Access Limitations

Source: https://docs.searchable.com/integrations/mcp

Understand the scope of data access provided by the MCP server.

```APIDOC
## Data Access

### Limitations

The MCP server provides **read-only access** to your Searchable data. It is designed to prevent unauthorized modifications or deletions. Specifically, the server cannot:

*   Modify your projects or settings.
*   Delete any data.
*   Access other users' projects.
*   Perform actions on your behalf.
```

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

### Content & Articles API

Source: https://docs.searchable.com/integrations/mcp

Endpoints for listing articles and retrieving the full content of a specific article.

```APIDOC
## GET /websites/searchable/content/list_articles

### Description
List articles for a project, including their titles, status, and topics.

### Method
GET

### Endpoint
/websites/searchable/content/list_articles

### Parameters
#### Query Parameters
- **projectId** (string) - Required - Project ID
- **status** (string) - Optional - "draft", "published", or "all" (default: "all")
- **limit** (integer) - Optional - Max articles to return (default: 50, max: 100)

### Response
#### Success Response (200)
- **articles** (array) - Article titles, status, topics, keywords, and metadata.

### Response Example
{
  "articles": [
    {
      "title": "Introduction to Searchable API",
      "status": "published",
      "topics": ["API", "Documentation"],
      "keywords": ["searchable", "api", "integration"]
    },
    {
      "title": "Getting Started with Site Audits",
      "status": "draft",
      "topics": ["SEO", "Audits"],
      "keywords": ["searchable", "audit", "seo"]
    }
  ]
}
```

```APIDOC
## GET /websites/searchable/content/get_article

### Description
Get a single article with its full content, including HTML/markdown, outline, and metadata.

### Method
GET

### Endpoint
/websites/searchable/content/get_article

### Parameters
#### Query Parameters
- **articleId** (string) - Required - Article ID

### Response
#### Success Response (200)
- **article** (object) - Complete article details including content, outline, FAQs, AEO/SEO metadata.

### Response Example
{
  "article": {
    "title": "Introduction to Searchable API",
    "content": "<p>This article explains...</p>",
    "outline": ["Introduction", "Endpoints", "Use Cases"],
    "faqs": [{"question": "How do I authenticate?", "answer": "Use your API key..."}],
    "seo_metadata": {"title": "Searchable API Guide", "description": "Learn how to integrate..."}
  }
}
```

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

### Site Audits API

Source: https://docs.searchable.com/integrations/mcp

Endpoints for retrieving website audit information, including issues, page scores, and monitored pages.

```APIDOC
## GET /websites/searchable/site_audits/get_website_issues

### Description
Get current website issues from Searchable's site auditor, grouped by severity.

### Method
GET

### Endpoint
/websites/searchable/site_audits/get_website_issues

### Parameters
#### Query Parameters
- **projectId** (string) - Required - Project ID
- **status** (string) - Optional - "open", "resolved", or "all" (default: "open")

### Response
#### Success Response (200)
- **issues** (object) - Issues grouped by severity (critical, high, medium, low) with descriptions and affected pages.

### Response Example
{
  "issues": {
    "critical": [
      {
        "description": "Missing alt text for images",
        "affected_pages": ["/index.html", "/about.html"]
      }
    ],
    "high": [],
    "medium": [],
    "low": []
  }
}
```

```APIDOC
## GET /websites/searchable/site_audits/get_page_audits

### Description
Get page audit scores for a project, including technical, content, and AEO scores.

### Method
GET

### Endpoint
/websites/searchable/site_audits/get_page_audits

### Parameters
#### Query Parameters
- **projectId** (string) - Required - Project ID

### Response
#### Success Response (200)
- **page_scores** (object) - Technical, content, and AEO (AI Engine Optimization) scores for each monitored page.

### Response Example
{
  "page_scores": {
    "/index.html": {
      "technical_score": 85,
      "content_score": 92,
      "aeo_score": 78
    },
    "/about.html": {
      "technical_score": 90,
      "content_score": 88,
      "aeo_score": 82
    }
  }
}
```

```APIDOC
## GET /websites/searchable/site_audits/get_monitored_pages

### Description
Get a list of all monitored pages for a project, including their status and issue counts.

### Method
GET

### Endpoint
/websites/searchable/site_audits/get_monitored_pages

### Parameters
#### Query Parameters
- **projectId** (string) - Required - Project ID

### Response
#### Success Response (200)
- **pages** (array) - List of monitored pages with URLs, types, issue counts, and tracking status.

### Response Example
{
  "pages": [
    {
      "url": "/index.html",
      "type": "html",
      "issue_count": 5,
      "tracking_status": "tracked"
    },
    {
      "url": "/about.html",
      "type": "html",
      "issue_count": 2,
      "tracking_status": "tracked"
    }
  ]
}
```

```APIDOC
## GET /websites/searchable/site_audits/get_issue_details

### Description
Get detailed information about specific types of issues, including affected pages and recommendations.

### Method
GET

### Endpoint
/websites/searchable/site_audits/get_issue_details

### Parameters
#### Query Parameters
- **projectId** (string) - Required - Project ID
- **issueType** (string) - Required - "technical" or "content"

### Response
#### Success Response (200)
- **issue_details** (object) - Unique issue types, affected pages, and fix recommendations.

### Response Example
{
  "issue_details": {
    "type": "Missing meta description",
    "affected_pages": ["/index.html", "/services.html"],
    "recommendations": "Add a concise and relevant meta description to each page."
  }
}
```

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

### Implement Article Schema (JSON)

Source: https://docs.searchable.com/using-searchable/understanding-scores

This JSON-LD snippet demonstrates how to implement the Article schema for a web page. It includes essential properties like headline, author, datePublished, image, and publisher details, crucial for search engines to understand article content.

```json
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "Your Article Title",
  "author": {
    "@type": "Person",
    "name": "Author Name"
  },
  "datePublished": "2025-01-15",
  "image": "https://example.com/image.jpg",
  "publisher": {
    "@type": "Organization",
    "name": "Your Company",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  }
}
```

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

### Configure Robots.txt for Searchable Bot

Source: https://docs.searchable.com/using-searchable/troubleshooting

This snippet shows the correct configuration for your robots.txt file to allow the SearchableBot crawler access to your site. Ensure this is correctly implemented to prevent audit timeouts.

```text
User-agent: SearchableBot
Allow: /

```
Tokens:
Raw