Response Format
All DorkList API responses follow a consistent JSON structure for easy parsing and error handling.
Standard Response Structure
Every API response contains a success boolean to indicate the request status.
Successful Response
json
{ "success": true, "data": { // Response data varies by endpoint }, "pagination": { // Only included for list endpoints "page": 1, "limit": 20, "total": 100, "hasMore": true }}Error Response
json
{ "success": false, "error": { "code": "ERROR_CODE", "message": "Human-readable error description" }}Response Fields
| Field | Type | Description |
|---|---|---|
| success | boolean | true if request succeeded, false otherwise |
| data | object | Contains the response payload (only on success) |
| error | object | Contains error details (only on failure) |
| error.code | string | Machine-readable error code |
| error.message | string | Human-readable error description |
| pagination | object | Pagination info (list endpoints only) |
Pagination
List endpoints (/dorks, /saved) include pagination metadata:
| Field | Type | Description |
|---|---|---|
| page | integer | Current page number |
| limit | integer | Number of items per page |
| total | integer | Total number of items across all pages |
| hasMore | boolean | Whether more pages are available |
Paginating Through Results
javascript
async function getAllDorks() { const allDorks = []; let page = 1; let hasMore = true; while (hasMore) { const response = await fetch( `https://dorklist.com/api/v1/dorks?page=${page}&limit=100`, { headers: { 'Authorization': `Bearer ${API_KEY}` } } ); const { data, pagination } = await response.json(); allDorks.push(...data.dorks); hasMore = pagination.hasMore; page++; } return allDorks;}Response Headers
The API returns these headers with every response:
| Header | Description |
|---|---|
| Content-Type | Always application/json |
| X-RateLimit-Limit | Your daily request limit |
| X-RateLimit-Remaining | Requests remaining today |
| X-RateLimit-Reset | Unix timestamp when limit resets |
| Access-Control-Allow-Origin | CORS header (set to *) |
Content Type
All responses are returned as JSON. Always set the Accept header to application/json in your requests:
bash
curl -X GET "https://dorklist.com/api/v1/dorks" \ -H "Authorization: Bearer dk_your_api_key_here" \ -H "Accept: application/json"Parsing Responses
Here's the recommended pattern for handling API responses:
javascript
async function apiRequest(endpoint, params = {}) { const url = new URL(`https://dorklist.com/api/v1/${endpoint}`); Object.entries(params).forEach(([key, value]) => { url.searchParams.append(key, value); }); const response = await fetch(url, { headers: { 'Authorization': `Bearer ${API_KEY}`, 'Accept': 'application/json' } }); // Check rate limit headers const remaining = response.headers.get('X-RateLimit-Remaining'); if (remaining && parseInt(remaining) < 10) { console.warn(`Low rate limit: ${remaining} requests remaining`); } const data = await response.json(); // Always check the success field if (!data.success) { throw new Error(`API Error [${data.error.code}]: ${data.error.message}`); } return data;}// Usagetry { const { data, pagination } = await apiRequest('dorks', { page: 1, limit: 50 }); console.log(`Fetched ${data.dorks.length} of ${pagination.total} dorks`);} catch (error) { console.error(error.message);}