API Reference

eshopSEO API

Integrate product and category SEO optimization into any system. Asynchronous processing, webhooks, and full multi-language support.

Base URL

https://api.eshopseo.com/api/v1

Key format

eseo_live_<32-hex-chars>

Rate limit

60 requests / minute per key

Credits

1 credit/call · 4 credits with web enrich

Authentication

All API requests require an X-API-Key header with a valid API key. Generate keys from the API Access dashboard.

Header

X-API-Key: eseo_live_your_key_here

Exceeding the rate limit returns 429 Too Many Requests.

Async flow

Submit an optimization request → receive 202 Accepted with a job_id
Receive the result via webhook (recommended) or poll GET /jobs/{job_id}
Credits are reserved on submit and refunded if the job fails

Sequence

Client                              eshopSEO API
  │                                       │
  │  POST /optimize/product               │
  │──────────────────────────────────────▶│
  │                                       │
  │  202 { job_id, status: "pending" }    │
  │◀──────────────────────────────────────│
  │                                       │  (background)
  │  POST webhook_url                     │
  │◀──────────────────────────────────────│
  │  { job_id, status, result }           │

Optimize product

POST/api/v1/optimize/product

Request body

Parameter	Type	Req	Description
`product_name`	string	✅	Product name (max 500 chars)
`current_description`	string		Current product description (max 10,000 chars)
`brand.name`	string	✅	Brand / store name
`brand.usps`	string		Unique selling propositions
`brand.info`	string		Brand description / context
`template`	string		Custom prompt template for description style
`language`	string		Target language code (default: en). Any language.
`enrich_from_web`	boolean		Search web for product specs (default: false). Costs 4 credits instead of 1.
`webhook_url`	string		URL to POST results when complete

Example request

{
  "product_name": "Nike Air Max 90",
  "current_description": "<p>Classic sneaker with visible Air cushioning...</p>",
  "brand": {
    "name": "SneakerShop",
    "usps": "Free shipping, 30-day returns",
    "info": "Premium athletic footwear retailer since 2010"
  },
  "language": "en",
  "enrich_from_web": true,
  "webhook_url": "https://yoursite.com/hooks/eshopseo"
}

Response — 202 Accepted

{
  "ok": true,
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "credits_remaining": 249
}

Optimize category

POST/api/v1/optimize/category

Request body

Parameter	Type	Req	Description
`category_name`	string	✅	Category name (max 500 chars)
`current_description`	string		Current category description
`brand.name`	string	✅	Brand / store name
`brand.usps`	string		Unique selling propositions
`brand.info`	string		Brand description / context
`category_url`	string		URL to scrape for product context
`category_context`	string		Free text describing the category (for new categories)
`language`	string		Target language (default: en)
`is_new_category`	boolean		If true, uses category_context instead of scraping URL
`webhook_url`	string		URL to POST results when complete

Existing category

{
  "category_name": "Running Shoes",
  "current_description": "Our running shoes collection...",
  "brand": {
    "name": "SneakerShop",
    "usps": "Free shipping, 30-day returns"
  },
  "category_url": "https://sneakershop.com/running-shoes",
  "language": "en",
  "is_new_category": false
}

New category

{
  "category_name": "Trail Running Shoes",
  "brand": { "name": "SneakerShop" },
  "category_context": "Off-road running shoes for mountain trails. Brands include Salomon, Hoka, La Sportiva.",
  "language": "en",
  "is_new_category": true
}

Job status

GET/api/v1/jobs/{job_id}

Statuses: pending → processing → completed | failed

Product result

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "endpoint": "product",
  "result": {
    "product_name_seo": "Nike Air Max 90 Men's Running Shoes",
    "description": "<p>The Nike Air Max 90 delivers visible Air cushioning...</p>",
    "meta_title": "Nike Air Max 90 | Men's Running Shoes - SneakerShop",
    "meta_description": "Shop the Nike Air Max 90 with visible Air cushioning...",
    "sef_url": "nike-air-max-90-mens-running-shoes"
  },
  "error_message": null,
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:12Z"
}

Category result

{
  "job_id": "...",
  "status": "completed",
  "endpoint": "category",
  "result": {
    "category_name_seo": "Men's Running Shoes",
    "description": "<p>Find the right running shoes for your stride...</p>",
    "meta_title": "Running Shoes for Men | SneakerShop",
    "meta_description": "Browse our collection of men's running shoes...",
    "sef_url": "mens-running-shoes"
  }
}

Credits

Each optimization call costs 1 credit. When enrich_from_web is enabled, the call costs 4 credits due to additional web scraping and enrichment. Credits are reserved on submit and refunded if the job fails.

Get balance

GET/api/v1/credits/balance

{ "credits": 248 }

Purchase credits

POST/api/v1/credits/purchase

Pack	Credits	Price	Per call
`api_500`	500	€50	€0.10
`api_2500`	2,500	€200	€0.08
`api_10000`	10,000	€500	€0.05

Usage history

GET/api/v1/usage?limit=50&offset=0

{
  "usage": [
    {
      "id": "...",
      "endpoint": "product",
      "status": "completed",
      "credits_consumed": 1,
      "created_at": "2025-01-15T10:30:00Z",
      "completed_at": "2025-01-15T10:30:12Z"
    }
  ],
  "total": 42
}

Webhooks

When you provide a webhook_url, the API will POST the result when the job completes. If delivery fails, the result remains available via polling.

Payload

{
  "job_id": "550e8400-...",
  "status": "completed",
  "result": {
    "product_name_seo": "...",
    "description": "...",
    "meta_title": "...",
    "meta_description": "...",
    "sef_url": "..."
  }
}

Signature verification

Each webhook includes an X-eshopSEO-Signature header with an HMAC-SHA256 signature of the payload body.

Python

import hmac, hashlib

def verify_webhook(payload_bytes, signature, secret):
    expected = hmac.new(secret.encode(), payload_bytes, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Idempotency

To prevent duplicate charges on retries, include an X-Idempotency-Key header. If a request with the same key was already processed, the API returns the existing job.

X-Idempotency-Key: your-unique-request-id

Error codes

Status	Meaning
`200`	Success
`202`	Job accepted (async processing started)
`400`	Bad request (invalid parameters)
`401`	Invalid or missing API key
`402`	Insufficient credits
`404`	Resource not found
`422`	Validation error
`429`	Rate limit exceeded (60 req/min)
`500`	Server error

Error format

{ "detail": "Insufficient API credits" }

Code examples

cURL — Full workflow

# Submit product optimization
curl -X POST https://api.eshopseo.com/api/v1/optimize/product \
  -H "X-API-Key: eseo_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "product_name": "Nike Air Max 90",
    "current_description": "Classic sneaker...",
    "brand": {"name": "SneakerShop", "usps": "Free shipping", "info": ""},
    "language": "en"
  }'

# Poll for result
curl https://api.eshopseo.com/api/v1/jobs/YOUR_JOB_ID \
  -H "X-API-Key: eseo_live_your_key_here"

# Check credit balance
curl https://api.eshopseo.com/api/v1/credits/balance \
  -H "X-API-Key: eseo_live_your_key_here"

Need help? support@eshopseo.com