API Reference

Node.js SDK

The official Node.js client wraps the REST API with full TypeScript support. Zero runtime dependencies, Node.js 18+ native fetch.

npm install @svg.dog/svgdog

import { optimize } from '@svg.dog/svgdog';
import fs from 'node:fs';

const result = await optimize(fs.readFileSync('icon.svg'), {
  apiKey: process.env.SVGDOG_API_KEY,
});

fs.writeFileSync('icon.min.svg', result.svg);
console.log(`Saved ${result.savingsPercent.toFixed(1)}%`);

Authentication

Pass your API key as a Bearer token in the Authorization header. You can get a free key at svg.dog.

Authorization: Bearer svgd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Plan limits

Optimize a single SVG

Auth: Optional

Uploads an SVG file and returns the optimized version. Anonymous requests are capped at 20/day. Free-plan keys allow up to 500/month.

Request

curl -X POST https://api.svg.dog/v1/optimize \
  -H "Authorization: Bearer <your-key>" \
  -F "file=@icon.svg"

Response

# Binary SVG file returned directly
# Response headers:
X-Original-Size: 4821
X-Optimized-Size: 1204
X-Savings-Percent: 75.04
X-Cached: false

Optimize an SVG from URL

Auth: Required (Free or Pro)

Fetches an SVG from a public URL, optimizes it, and returns the result.

Request

curl -X POST https://api.svg.dog/v1/optimize/url \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/icon.svg"}'

Response

# Optimized SVG file returned directly

Optimize multiple SVGs

Auth: Required (Free or Pro)

Upload up to 10 (Free) or 50 (Pro) SVG files in a single request. Returns a JSON array of results.

Request

curl -X POST https://api.svg.dog/v1/optimize/batch \
  -H "Authorization: Bearer <your-key>" \
  -F "files=@icon1.svg" \
  -F "files=@icon2.svg"

Response

[
  {
    "filename": "icon1.svg",
    "success": true,
    "original_size": 4821,
    "optimized_size": 1204,
    "savings_percent": 75.04,
    "optimized": "<svg>...</svg>"
  },
  {
    "filename": "icon2.svg",
    "success": false,
    "error": "Invalid SVG"
  }
]

Get usage statistics

Auth: Required

Returns your current monthly usage, including total optimizations, billable count, and volume saved.

Request

curl https://api.svg.dog/v1/usage \
  -H "Authorization: Bearer <your-key>"

Response

{
  "plan": "pro",
  "month": "2026-04",
  "optimizations": {
    "total": 1240,
    "billable": 740,
    "limit": null,
    "remaining": null
  },
  "volume": {
    "total_input_bytes": 15204800,
    "total_output_bytes": 3801200,
    "total_saved_bytes": 11403600
  }
}

Health check

Auth: None

Returns the current API status. Useful for monitoring integrations.

Request

curl https://api.svg.dog/v1/health

Response

{
  "status": "ok"
}

Error codes