DesignSkill Agent | Developer Documentation

01 // AUTHENTICATION

Authentication

All requests to the DesignSkill Agent Developer API must provide an authorized API key in the request headers. We use the standard Bearer Token scheme:

HTTP Header

Authorization: Bearer dsk_live_YOUR_API_KEY

Ensure this header is supplied with all requests to the /api/v1/* endpoints. Unauthenticated requests are rejected with a 401 Unauthorized response.

02 // SDK EXAMPLES

First Request Example

Use the following sample cURL and language snippets to run your first scrape and extraction. Replace dsk_live_YOUR_API_KEY with your raw key:

cURL / BASH

curl -X POST https://scraper.chowkar.in/api/v1/scrape \
  -H "Authorization: Bearer dsk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

NODE.JS

const fetch = require('node-fetch');

async function runScrape() {
  const res = await fetch('https://scraper.chowkar.in/api/v1/scrape', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer dsk_live_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url: 'https://example.com' })
  });
  const data = await res.json();
  console.log(data);
}

runScrape();

PYTHON

import requests

headers = {
    'Authorization': 'Bearer dsk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
}
payload = {'url': 'https://example.com'}

res = requests.post('https://scraper.chowkar.in/api/v1/scrape', headers=headers, json=payload)
print(res.json())

GO

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    url := "https://scraper.chowkar.in/api/v1/scrape"
    payload, _ := json.Marshal(map[string]string{"url": "https://example.com"})
    
    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
    req.Header.Set("Authorization", "Bearer dsk_live_YOUR_API_KEY")
    req.Header.Set("Content-Type", "application/json")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    fmt.Println("Status:", resp.Status)
}

03 // ERROR HANDLING

Error Handling

When an API operation encounters a validation check, authorization failure, or extraction crash, the system returns a standard JSON error envelope:

JSON Response

{
  "error": {
    "code": "INVALID_URL",
    "message": "Safety violation: Target domain resolves to a private IP space.",
    "requestId": "req_5f2d1e00f9"
  }
}

INVALID_REQUEST: Missing payload parameter or type mismatch.
INVALID_URL: Domain resolves to local loopback (SSRF defense protection).
SCRAPE_FAILED: The Puppeteer browser pool timed out trying to open the page.
UNAUTHORIZED: API key is invalid or has been revoked by key rotation.

04 // RATE LIMITS

Rate Limits

We enforce standard IP rate-limiting to protect backend Puppeteer memory allocations:

Global IP Rate Limit: 100 requests per minute.
Scraping Concurrency: 3 concurrent scraping worker operations per client.
Crossing these thresholds returns a 429 Too Many Requests response.

05 // BILLING

Credits & Billing Semantics

All operations run on a credit allocation billing model:

API Endpoint	Credit Cost	Reason
`POST /api/v1/scrape`	1 Credit	Chrome DOM render and computed styling calculation.
`POST /api/v1/enrich`	1 Credit	Gemini LLM semantic context analysis.
`POST /api/v1/generate-plugin`	0 Credits	Compilation into Skill ZIP pack format.

Important Deduction Rules:

Pre-Deduction: Credits are charged immediately upon execution start.
Failed Scrapes: If a scrape fails with 500 due to target page network timeouts or loopback rules, 1 credit is still charged to cover compute allocation.
Gate Rejections: If blocked by rate limits (429), auth errors (401), or server capacity limits (503), 0 credits are consumed.

06 // RETRIES

Retries & Backoff

For robust production integrations, do not trigger sequential instant retries when receiving 429 or 503 status codes.

Implement Exponential Backoff with Random Jitter to allow scraper pool resources to free up:

Backoff Formula

t_wait = (2^attempt * 1000) ms + RandomJitter

Do not retry if you receive 402 Payment Required (credit balance exhausted) or 400 Bad Request (malformed parameters).

07 // KEY SAFETY

Key Safety

Your API key is a direct credential to your credit balance:

Secure Environment Variables: Never hardcode your API key in browser scripts or frontend assets. Keep keys restricted to backend server processes (e.g. Node process environments or database secrets).
Rotation Mechanics: Key rotation invalidates your prior key immediately. The new raw key is shown only once and cannot be re-rendered. Store it in a secure password vault or secrets manager.

08 // TROUBLESHOOTING

Troubleshooting

Review these guidelines to interpret scraping behavior and get support:

Chrome cold boots: On first launch, the headless Chromium sandbox may experience a cold boot delay (up to 4–6 seconds) before responding to /api/scrape.
429/503 limits: A 503 error indicates the Puppeteer pool has occupied all concurrency slots (max 3). Wait 5–10 seconds and retry using the backoff guidelines.
Direct Support: If your key request is pending more than 24 hours, email the administrator with your payment UTR at chowkar.tester@gmail.com.

09 // CLAUDE MCP

Claude & MCP Integration

DesignSkill Agent features a Model Context Protocol (MCP) server adapter, letting LLM clients such as Claude connect to local tools through a standard JSON-RPC 2.0-based protocol. This allows AI assistants to autonomously invoke the design system scraper over standard stdio JSON-RPC.

1. Claude Desktop Configuration

To add DesignSkill Agent as a custom tool in your Claude Desktop app, edit your local configuration file. You can open it via the app's settings ("Developer" → "Edit Config") or locate it manually at:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following server declaration inside the "mcpServers" block. Note that the path in "args" must point to the absolute path of your local cloned directory:

JSON CONFIG

{
  "mcpServers": {
    "designskill-agent": {
      "command": "node",
      "args": ["/absolute/path/to/designskill-scraper/mcp-server/index.js"],
      "env": {
        "DESIGNSKILL_API_KEY": "YOUR_DESIGNSKILL_API_KEY",
        "DESIGNSKILL_API_URL": "https://scraper.chowkar.in"
      }
    }
  }
}

Windows Path Placeholder Example: Replace /absolute/path/... with C:\\path\\to\\designskill-scraper\\mcp-server\\index.js (ensure paths use escaped double-backslashes in JSON configuration).

After saving your configuration file, fully restart the Claude Desktop application. If successful, you will see a "hammer" icon in the lower-right corner of the chat input displaying the generate_design_skill tool!

2. Claude Code (CLI) Configuration

Downstream terminal-based AI agents like Claude Code can connect to the tool by registering the MCP server using the CLI:

BASH

# Register the server using an absolute path to index.js
# For macOS/Linux:
claude mcp add designskill-agent -- node "/absolute/path/to/designskill-scraper/mcp-server/index.js"

# For Windows:
claude mcp add designskill-agent -- node "C:\path\to\designskill-scraper\mcp-server\index.js"

Load the key in your active terminal context before launching Claude Code, or pass it via your environment profile:

BASH

export DESIGNSKILL_API_KEY="YOUR_DESIGNSKILL_API_KEY"
export DESIGNSKILL_API_URL="https://scraper.chowkar.in"
claude

To verify active tools in Claude Code, execute:

BASH

claude mcp list

3. Troubleshooting MCP Connections

Missing Tools Hammer: Check the absolute path specified in the config. If Node fails to find index.js, the server won't boot and the tool list will remain empty. Inspect Desktop logs in %APPDATA%\Claude\Logs\mcp.log (Windows) or ~/Library/Logs/Claude/mcp.log (macOS) to view startup errors.
Environment Paths: Verify that node is registered on your system path. If the executable cannot be located on system boot, Claude won't be able to invoke the MCP server processes.
URL Constraints: All target URLs must be public domains. Requesting loopback addresses (e.g. localhost, 127.0.0.1) is blocked for SSRF security and will return a validation error.

4. MCP Distribution Modes & Roadmap

Currently, connecting the DesignSkill MCP adapter requires a local clone of the repository. The upcoming roadmap paths outline planned distribution packages:

Distribution Mode	Setup Requirements	Status / Best For
Local File Path	Clone repository and point args to `index.js`	Available Now (Devs & Contributors)
NPM Package (npx)	Node.js installed locally; no cloning required	Coming Soon (Public Onboarding)
Desktop Extension	One-click install from Claude Desktop App	Future Roadmap (End-user simplicity)

⚠️ Windows NPX Caveat: When executing via npx on Windows, some shells require command wrapping (e.g. cmd /c npx ...). We recommend the local file path as the stablest fallback for Windows development environments.