DEVELOPER DOCUMENTATION

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:

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.

Support

Support requests are routed through the portal and the public support channels. For billing disputes, key rotation issues, or failed deep jobs, include the request ID, job ID, and the exact target URL in your note.

• Operational issues: If the service returns repeated 429 or 503 responses, wait for the backoff window and retry with a new idempotency key.
• Credit or billing questions: Use the top-up history in the portal and keep the transfer UTR ready for operator review.
• Direct contact: Email chowkar.tester@gmail.com for account or access issues that require manual assistance.

Async Job-Based API

For resource-intensive deep scraping operations (POST /api/v1/scrape/deep), the platform utilizes an asynchronous job queue. Instead of holding HTTP connections open during multi-phase browser analysis, the request is immediately enqueued, returning a job handle.

A. The Location Header Protocol

When submitting a deep scrape request, the API will respond with 202 Accepted. The response contains a standard HTTP Location header specifying the status polling resource:

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

HTTP/1.1 202 Accepted
Location: /api/v1/jobs/3a8f9c0e-1234-5678-abcd-ef0123456789

{
  "success": true,
  "jobId": "3a8f9c0e-1234-5678-abcd-ef0123456789",
  "statusUrl": "/api/v1/jobs/3a8f9c0e-1234-5678-abcd-ef0123456789",
  "creditsCharged": 5,
  "status": "queued"
}

B. Status Polling

To retrieve progress details or result payloads, poll the status endpoint with standard 200 OK responses:

curl -H "Authorization: Bearer dsk_live_YOUR_API_KEY" \
  https://designskillagent.online/api/v1/jobs/3a8f9c0e-1234-5678-abcd-ef0123456789

{
  "jobId": "3a8f9c0e-1234-5678-abcd-ef0123456789",
  "status": "processing",
  "progress": 50,
  "activePhase": "scrape",
  "startedAt": "2026-07-11T18:12:00.000Z",
  "attemptCount": 1
}

{
  "jobId": "3a8f9c0e-1234-5678-abcd-ef0123456789",
  "status": "completed",
  "progress": 100,
  "mode": "deep",
  "quotedCredits": 5,
  "finalCredits": 5,
  "artifactType": "deep_pack",
  "enrichmentMode": "live_ai",
  "enrichmentStatus": "completed",
  "billingOutcome": "full_charge",
  "resultUrl": "/output/jobs/3a8f9c0e-1234-5678-abcd-ef0123456789.json",
  "completedAt": "2026-07-11T18:12:12.000Z",
  "runtimeMs": 12000,
  "outputSummary": {
    "colorsCount": 12,
    "fontsCount": 2,
    "fontScaleCount": 5,
    "componentsCount": 28,
    "animationsCount": 3
  }
}

{
  "jobId": "3a8f9c0e-1234-5678-abcd-ef0123456789",
  "status": "completed",
  "progress": 100,
  "mode": "deep",
  "quotedCredits": 5,
  "finalCredits": 4,
  "artifactType": "deep_pack",
  "enrichmentMode": "fallback",
  "enrichmentStatus": "failed_upstream",
  "billingOutcome": "partial_refund",
  "resultUrl": "/output/jobs/3a8f9c0e-1234-5678-abcd-ef0123456789.json",
  "completedAt": "2026-07-11T18:12:12.000Z",
  "runtimeMs": 12000,
  "outputSummary": {
    "colorsCount": 12,
    "fontsCount": 2,
    "fontScaleCount": 5,
    "componentsCount": 28,
    "animationsCount": 3
  }
}

C. Recommended Polling Strategy

To optimize client performance and respect server pool capacities, developers should implement an adaptive short-polling backoff:

• Initiate status checks starting at a 5-second check interval.
• On each poll return where status is still queued or processing, increase the wait interval by 2.5 seconds.
• Cap maximum polling intervals at 30 seconds.
• Apply a small randomized jitter (e.g. +/- 500ms) to polling offsets to avoid synchronized network retry storms.

D. Idempotency Key Semantics

Async jobs support idempotent execution via the Idempotency-Key header:

• Replay Path: If a request is retried with the same Idempotency-Key and identical request payload, the server replays the existing job record, returning 202 (or 200 if completed) along with the X-Idempotent-Replay: true response header. No duplicate credits are charged.
• Conflict Path: Submitting the same Idempotency-Key but with a modified request payload will reject the transaction with a 409 Conflict status code to guarantee state integrity.

Error Handling

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

{
  "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.
• See All Error Cases: Consult the dedicated Errors & Refunds directory for a full list of code definitions, debugging checklists, and troubleshooting steps.

Credits & Billing Semantics

All operations run on a credit allocation billing model:

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.
• Detailed Policies: Read our complete Errors & Refunds guide for details on automatic refunds, worker failures, and credit adjustment guidelines.

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.

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:

{
  "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://designskillagent.online"
      }
    }
  }
}

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:

# 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:

export DESIGNSKILL_API_KEY="YOUR_DESIGNSKILL_API_KEY"
export DESIGNSKILL_API_URL="https://designskillagent.online"
claude

To verify active tools in Claude Code, execute:

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:

⚠️ 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.