Api

svgicons-com

OpenAPI spec, TypeScript SDK, examples, recipes, and use cases for the svgicons.com Pro API.

#design-systems #developer-tools #icon-library #icons #mcp #openapi #react #rest-api #svelte #svg

Svg/icons API

OpenAPI spec, SDK, examples, recipes, and developer use cases for the svgicons.com Pro API.

This repository is the developer home for the official svgicons.com Pro API. It documents the current Pro REST API, the hosted MCP endpoint as a related workflow, companion CLI workflows, and the alpha SDK package for teams that want to search, export, audit, and integrate open-source SVG icons in developer workflows.

API docs: https://svgicons.com/developers/api
MCP docs: https://svgicons.com/developers/mcp
CLI repo: https://github.com/svgicons-com/cli
API repo: https://github.com/svgicons-com/api

Current Status

The live REST API is mounted at https://svgicons.com/api/pro. It uses scoped Pro API tokens created from a Svg/icons account. The current website OpenAPI document is published at:

https://svgicons.com/openapi/pro-api.json

This repo keeps the API-repo OpenAPI source at openapi/svgicons.openapi.yaml. The TypeScript SDK package source lives in packages/js and should be treated as alpha until it is published to npm.

Authentication Required

This repository documents the official svgicons.com Pro API. The documented /api/pro endpoints require a svgicons.com Pro API token unless an endpoint is explicitly documented otherwise by the OpenAPI source.

Examples use SVGICONS_API_TOKEN as the environment variable and YOUR_API_TOKEN as the placeholder token value. Do not expose Pro API tokens in public frontend JavaScript. Use server-side routes, backend proxies, server actions, secure workers, or CI jobs for token-authenticated API calls.

There is currently no official unauthenticated public icon REST API documented in this repository. Public browsing and searching are available on svgicons.com, but this repo's API workflows are token-authenticated Pro API workflows.

The only currently unauthenticated /api/pro endpoint in the OpenAPI source is GET /api/pro/scopes. It is API metadata/discovery for the Pro API scope catalog, not a free icon search or icon download API.

Release Status

This repository documents the live svgicons.com Pro API. The SDK source is available in this repo, but the npm package has not been published yet.

SDK npm publication: pending package review and release approval.
Live REST API: /api/pro.
Planned REST API: /api/v1, not live.
MCP: separate JSON-RPC over /mcp.

See docs/RELEASE_CHECKLIST.md, docs/PUBLISHING.md, and docs/API_VERSIONING.md.

What You Can Build

Design-system icon picker backed by Svg/icons search.
Command palette icon search for internal tools.
SVG sprite generator for selected Icon Collections.
React, Vue, and Svelte icon exports from Icon Collections.
AI coding assistant and MCP workflows for icon search and collection generation.
CI license/provenance audit using the companion CLI.

Quick Start

List the current Pro API scopes. This API metadata endpoint does not require a token, but it does not search or return icons.

curl https://svgicons.com/api/pro/scopes

Search icons with a Pro API token.

curl -H "Authorization: Bearer YOUR_API_TOKEN" "https://svgicons.com/api/pro/search?q=arrow"

Or keep the token in an environment variable:

export SVGICONS_API_TOKEN="YOUR_API_TOKEN"

curl "https://svgicons.com/api/pro/search?q=settings&limit=5" \
  -H "Authorization: Bearer $SVGICONS_API_TOKEN" \
  -H "Accept: application/json"

Fetch an icon SVG payload by id.

curl "https://svgicons.com/api/pro/icons/33716/svg" \
  -H "Authorization: Bearer $SVGICONS_API_TOKEN" \
  -H "Accept: application/json"

Create an Icon Collection. The current REST route still uses the historical project-kits path segment.

curl "https://svgicons.com/api/pro/project-kits" \
  -X POST \
  -H "Authorization: Bearer $SVGICONS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"name":"Dashboard icons","framework":"react-ts","colorPolicy":"currentColor","namingPolicy":"pascal"}'

Queue a collection export after adding icons to the collection.

curl "https://svgicons.com/api/pro/project-kits/123/exports" \
  -X POST \
  -H "Authorization: Bearer $SVGICONS_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"formats":["react-ts","vue","license-manifest"],"options":{"typescript":true,"defaultSize":24}}'

TypeScript SDK

The local workspace package is packages/js and is named @svgicons-com/api-client. It covers the live /api/pro REST operations only.

Install from npm after the package is published:

npm install @svgicons-com/api-client

For local development in this repository:

npm install
npm run build

Use it from server-side code, backend services, CI jobs, or internal tools so Pro API tokens stay out of public browser bundles.

import { SvgiconsClient } from "@svgicons-com/api-client";

const client = new SvgiconsClient({
  token: process.env.SVGICONS_API_TOKEN,
});

const results = await client.search.icons({
  q: "arrow",
  limit: 20,
});

const svg = await client.icons.getSvg({
  icon: results.data[0]?.id ?? 33716,
});

console.log(svg.data.svg);

Core Examples

Node search icons - server-side script using client.search.icons().
Server-side token proxy - local browser UI backed by a Node server that keeps the token private.
Next.js icon picker - App Router pattern with server-side route handlers and a client picker.
SVG sprite generator - reads configured icon ids and writes a simple sprite using client.icons.getSvg().

All core examples use live svgicons.com Pro API behavior under /api/pro. They require SVGICONS_API_TOKEN to run, and validation does not make real network calls.

Advanced Examples

React command palette - command/search UI pattern backed by server-side API routes.
Design-system icons - approved icon manifest generation with source and license metadata.
CI license audit - provenance report generation and a GitHub Actions workflow template.
AI coding MCP workflow - REST helper plus MCP workflow notes; MCP remains separate JSON-RPC over /mcp.
Framework export workflow - create a Project Kit through the API and use the existing CLI for framework-oriented export workflows.

The advanced examples are templates and scripts. They do not imply the SDK is published to npm.

Recipes

Start with the recipes index for task-focused guides. Current recipes:

Search icons - query the live /api/pro/search endpoint with curl or the SDK.
Fetch SVG safely - retrieve SVG payloads and handle rendering responsibilities in your app.
Build a React icon picker - internal picker pattern with server-side token handling.
Build a command palette - keyboard-friendly icon search workflow.
Proxy API tokens in Next.js - App Router route handler pattern for keeping tokens private.
Generate an SVG sprite - build a simple sprite from selected icon ids.
Manage Project Kits - create collections, add icons, queue exports, and download artifacts.
Export icons to frameworks - combine API Project Kits with CLI framework export workflows.
Generate a license manifest - produce provenance reports from live metadata.
Use Svg/icons with MCP - keep REST helpers and hosted MCP JSON-RPC workflows separate.
Use Svg/icons in CI - run team-defined provenance checks in CI.

Recipes use live /api/pro behavior unless they explicitly describe a separate MCP or CLI workflow. They do not imply npm publication.

Use the CLI for local lockfiles, license checks, scanner workflows, and collection exports:

npm install -g @svgicons-com/cli
export SVGICONS_API_TOKEN="YOUR_API_TOKEN"

svgicons auth status
svgicons search "settings gear" --limit 5
svgicons collection export "Dashboard icons" --formats react-ts,license-manifest
svgicons license check --allow MIT,Apache-2.0 --fail

Token Safety

Treat Svg/icons API tokens like passwords.

Do not commit tokens to Git.
Use SVGICONS_API_TOKEN or a secret manager.
Keep tokens on the server side.
Do not put Pro API tokens in browser JavaScript.
Rotate a token immediately if it appears in a commit, log, screenshot, support request, or public issue.

See docs/TOKEN_SECURITY.md for safer environment variable and frontend proxy patterns.

Validation And CI

CI is configured for GitHub Actions with Node 22. It does not require SVGICONS_API_TOKEN, does not call the live API, and does not depend on the website or CLI repos being present.

Run the full local validation stack:

npm ci
npm run validate
git diff --check

Useful focused checks:

npm run check:secrets
npm run check:docs
npm run validate:openapi
npm run typecheck
npm run build
npm run test

See docs/CI.md and docs/MAINTAINER_CHECKLIST.md.

Repository Map

openapi/ - OpenAPI source and examples.
packages/js/ - alpha JavaScript/TypeScript SDK package source.
examples/ - minimal working examples.
recipes/ - task-focused guides.
use-cases/ - community use-case submissions.
docs/ - roadmap, token security, API versioning, CI, release, moderation, and link policy.

Live, Planned, And Beta Labels

This repo uses explicit status labels:

Live: implemented in the current website repo and safe to document.
Alpha: implemented or scaffolded, but not ready for stable public use.
Planned: intended repo work, not available yet.
Proposed: under consideration, not committed.

Do not treat future SDK methods, future examples, or future MCP tools as live until the source repo confirms them.

Community Use Cases

Share what you built with the Svg/icons API, SDK, examples, CLI workflows, or MCP-style workflows.

Start at use-cases/README.md.
Use use-cases/TEMPLATE.md for pull requests.
Review sample submissions in use-cases/examples/.
Use the GitHub issue form at .github/ISSUE_TEMPLATE/use-case.yml after issues are enabled for the repository.

Good submissions explain the problem solved, stack, API/SDK/CLI/MCP workflow used, token-handling approach, and a short code snippet. Optional project, demo, or repo links are allowed when they help developers understand the workflow.

Selected use cases may be featured in this repo or on svgicons.com with permission. Do not include real API tokens, private data, spam links, or fake claims.

External links are optional. Developers are not required to link back to svgicons.com.

License

MIT. See LICENSE.

Top categories

tailwind daisyui admin template popup mdsvex portfolio blog form ecommerce ui carousel auth dark seo image routing