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.