Listing Assistant API

Version 1.0.0

Base URL: https://listinghelper.kreativschicht.de

OpenAPI Spec: View YAML | View JSON

For interactive API documentation, import the OpenAPI spec into Postman or Insomnia.

Quick Start

1. Get an API Key

Option A: Self-Serve (Recommended) - Create a FREE API key instantly from the UI:

Visit the Get Started page:

🚀 Create FREE API Key

No signup required. Get your key in <10 seconds.

Option B: Admin Key (For Self-Hosted Deployments)

curl -X POST https://listinghelper.kreativschicht.de/api/admin/keys \
  -H "Content-Type: application/json" \
  -H "x-admin-key: YOUR_ADMIN_KEY" \
  -d '{"name": "My Key", "plan": "FREE"}'

Note: Requires ADMIN_BOOTSTRAP_KEY environment variable. Only for administrators.

2. Analyze a Product

curl -X POST https://listinghelper.kreativschicht.de/api/analyze \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "productDraft": {
      "title": "Handmade Leather Wallet",
      "category": "Accessories",
      "brand": "Artisan Goods"
    },
    "platforms": ["etsy"],
    "flags": {
      "enableTitles": true,
      "enableTags": true,
      "enableImageChecks": false
    }
  }'

API Endpoints

POST /api/analyze

Generate platform-optimized titles, tags, and image analysis.

Auth: x-api-key

GET /api/me

Get information about your API key.

Auth: x-api-key

GET /api/me/usage

Get usage statistics for your API key.

Auth: x-api-key | Query: ?days=30

POST /api/me/rotate-key

Rotate your API key (generates new key, invalidates old one).

Auth: x-api-key

POST /api/billing/checkout

Create a Stripe Checkout session to upgrade your plan.

Auth: x-api-key | Body: {"plan": "PRO"}

POST /api/billing/portal

Create a Stripe Customer Portal session for managing subscriptions.

Auth: x-api-key

POST /api/admin/keys

Create a new API key (admin only).

Auth: x-admin-key

GET /api/admin/keys

List all API keys (admin only).

Auth: x-admin-key

SDKs & Tools

TypeScript SDK

import { createClient } from '@listing-ai/sdk';

const client = createClient({
  baseUrl: 'https://listinghelper.kreativschicht.de',
  apiKey: 'YOUR_API_KEY',
});

const result = await client.analyze({
  productDraft: { title: 'Leather Wallet' },
  platforms: ['etsy'],
  flags: {
    enableTitles: true,
    enableTags: true,
    enableImageChecks: false,
  },
});

See /packages/sdk/README.md for full documentation.

CLI Tool

# Set base URL (optional, defaults to localhost:3000)
export LISTING_AI_BASE_URL="https://listinghelper.kreativschicht.de"
export LISTING_AI_API_KEY="YOUR_API_KEY"

# Analyze a product
listing-ai analyze --platform etsy --name "Leather Wallet" --pretty

# Check account info
listing-ai me --pretty

# View usage stats
listing-ai usage --days 30 --pretty

See /packages/cli/README.md for full documentation.

Authentication

Most API endpoints require authentication via the x-api-key header. Admin endpoints require the x-admin-key header instead.

# User endpoint (with API key)
curl -H "x-api-key: YOUR_API_KEY" https://listinghelper.kreativschicht.de/api/me

# Admin endpoint (with admin key)
curl -H "x-admin-key: YOUR_ADMIN_KEY" https://listinghelper.kreativschicht.de/api/admin/keys

Plan Limits

Plan	Titles/Run	Images/Run	Platforms/Run	Runs/Day
FREE	5	1	1	20
PRO	15	6	2	200
BUSINESS	30	12	3	2000