API Reference

LinkSnap provides a simple REST API for capturing web screenshots. All endpoints use JSON for requests and responses.

Base URL

https://api.linksnap.dev

Authentication

All API requests require authentication via Bearer token:

Authorization: Bearer lk_your_api_key

Get your API key from the Console.

Endpoints

Create Screenshot

POST /v1/screenshots

Capture a screenshot of a webpage.

Request Body

Parameter	Type	Required	Description
`url`	string	Yes	The URL to capture
`format`	string	No	Output format: `png`, `jpeg`, `webp`. Default: `png`
`quality`	number	No	Image quality (1-100). Default: 80
`fullPage`	boolean	No	Capture full page. Default: `false`
`viewport`	object	No	Viewport settings
`viewport.width`	number	No	Viewport width. Default: 1920
`viewport.height`	number	No	Viewport height. Default: 1080
`delay`	number	No	Wait time in ms before capture (0-10000). Default: 0
`blockAds`	boolean	No	Block ads and trackers. Default: `false`

Example Request

curl -X POST https://api.linksnap.dev/v1/screenshots \
  -H "Authorization: Bearer lk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "fullPage": true,
    "viewport": {
      "width": 1440,
      "height": 900
    }
  }'

Response

{
  "success": true,
  "data": {
    "id": "ss_abc123def456",
    "url": "https://cdn.linksnap.dev/screenshots/ss_abc123def456.png",
    "format": "png",
    "width": 1440,
    "height": 2500,
    "fileSize": 524288,
    "cached": false,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

Get Screenshot

GET /v1/screenshots/:id

Retrieve details about a specific screenshot.

Response

{
  "success": true,
  "data": {
    "id": "ss_abc123def456",
    "url": "https://cdn.linksnap.dev/screenshots/ss_abc123def456.png",
    "sourceUrl": "https://example.com",
    "format": "png",
    "width": 1440,
    "height": 2500,
    "fileSize": 524288,
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
}

List Screenshots

GET /v1/screenshots

List your recent screenshots.

Query Parameters

Parameter	Type	Description
`limit`	number	Max results (1-100). Default: 20
`cursor`	string	Pagination cursor

Response

{
  "success": true,
  "data": [
    {
      "id": "ss_abc123def456",
      "url": "https://cdn.linksnap.dev/screenshots/ss_abc123def456.png",
      "sourceUrl": "https://example.com",
      "format": "png",
      "createdAt": "2024-01-15T10:30:00.000Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "nextCursor": "ss_xyz789"
  }
}

Error Codes

Code	Status	Description
`INVALID_URL`	400	The provided URL is invalid or blocked
`INVALID_FORMAT`	400	Unsupported image format
`UNAUTHORIZED`	401	Missing or invalid API key
`QUOTA_EXCEEDED`	429	Monthly quota exhausted
`RATE_LIMITED`	429	Too many requests
`CAPTURE_FAILED`	500	Failed to capture screenshot
`TIMEOUT`	504	Page took too long to load

Error Response Format

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly screenshot quota exceeded. Please upgrade your plan."
  }
}

Rate Limits

Rate limits are per API key:

Plan	Requests/minute
Free	10
Basic	30
Pro	60
Team	120

When rate limited, you'll receive a 429 response with a Retry-After header.

Webhooks

Configure webhooks to receive notifications when screenshots are ready:

{
  "event": "screenshot.completed",
  "data": {
    "id": "ss_abc123def456",
    "url": "https://cdn.linksnap.dev/screenshots/ss_abc123def456.png",
    "status": "success"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Configure webhooks in your Console settings.

API Reference

On this page