Developers

Build on Listing Doctor. Use our REST API or MCP server to integrate Etsy listing optimization into your app, agent, or workflow.

REST API

OpenAPI 3.1

MCP Server

API Keys

Quick Start

1. Get an API key:

curl -X POST https://listingdr.com/api/v1/keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My App", "owner_id": "me"}'

2. Score a listing:

curl -X POST https://listingdr.com/api/v1/score \
  -H "Content-Type: application/json" \
  -H "x-api-key: ld_your_key_here" \
  -d '{
    "title": "Chesapeake Bay Map Print - Nautical Wall Art",
    "tags": ["chesapeake bay", "nautical map", "wall art", "coastal decor"],
    "description": "Beautiful hand-crafted map print...",
    "photos_count": 8,
    "alt_texts": ["Chesapeake Bay nautical map print"]
  }'

Response:

{
  "score": 72.5,
  "grade": "B",
  "breakdown": { "title_seo": 22/28, "tag_seo": 14/20, ... },
  "issues": [
    { "severity": "high", "message": "Only 4 tags — use all 13 slots" },
    { "severity": "medium", "message": "Title under 100 characters" }
  ]
}

REST API

All endpoints require an x-api-key header. Rate limits and usage are tracked per key.

POST

/api/v1/score

Score an Etsy listing across all 6 categories. Returns score (0-100), grade (A-F), category breakdown, issues, and fix suggestions.

{ "title": "...", "tags": [...], "description": "...", "photos_count": 10, "alt_texts": [...] }

POST

/api/v1/check-title

Quick title SEO check. Analyzes character length, keyword usage, punctuation, and structure.

{ "title": "Your Etsy listing title here" }

POST

/api/v1/check-tags

Tag analysis. Checks for duplicates, title overlap, tag count, and optimization opportunities.

{ "title": "...", "tags": ["tag1", "tag2", ...] }

POST

/api/v1/keys

Generate a new API key. Returns a ld_xxxx key with your selected tier limits.

{ "name": "My App", "owner_id": "your-id" }

GET

/api/v1/openapi.json

Full OpenAPI 3.1 specification. Machine-readable API documentation for code generation and agent integration.

MCP Server (for AI Agents)

Connect Listing Doctor directly to Claude, Cursor, Windsurf, or any MCP-compatible AI assistant. The MCP server runs locally and provides scoring tools without needing API keys.

Installation (Claude Desktop)

// Add to claude_desktop_config.json:
{
  "mcpServers": {
    "listing-doctor": {
      "command": "npx",
      "args": ["-y", "listing-doctor-mcp"]
    }
  }
}

score_listing

Full 100-point scoring with grade, breakdown, and prioritized issues

analyze_listing_url

Paste an Etsy URL — fetches the listing and scores it automatically

get_optimization_tips

Prioritized action items sorted by impact (critical → low)

check_title_seo

Quick title-only SEO analysis with specific fix suggestions

check_tags

Tag analysis with duplication detection and coverage scoring

Authentication & Rate Limits

Tier	Monthly Limit	Rate	Overage
Free	100 calls	10/min	Blocked
Starter	500 calls	30/min	$0.02/call
Pro	2,000 calls	60/min	$0.02/call
Business	10,000 calls	120/min	$0.01/call
Enterprise	Unlimited	Custom	N/A

Every response includes rate limit headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset