SDK Overview

The Quikturn Logo API can be used directly via REST (an <img> tag is all you need), but for deeper integration we publish two official packages:

Package	Purpose	Install
@quikturn/logos	URL builder, browser client, server client, web component	`npm i @quikturn/logos`
@quikturn/logos-react	React Provider, components, and hooks	`npm i @quikturn/logos-react`

The SDKs are optional. The REST API works with any language or HTTP client. Use the SDKs when you want typed errors, automatic retries, batch operations, or drop-in React components.

Installation

# Core SDK (universal + browser + server + web component)
npm install @quikturn/logos

# React components (optional)
npm install @quikturn/logos-react

pnpm add @quikturn/logos
pnpm add @quikturn/logos-react

yarn add @quikturn/logos
yarn add @quikturn/logos-react

Requirements: Node.js >= 18, TypeScript recommended.

Entry Points

@quikturn/logos ships four entry points so you import only what you need:

Import	Platform	Description
`@quikturn/logos`	Any	URL builder, types, constants — zero dependencies
`@quikturn/logos/client`	Browser	Blob URLs, retries, scrape polling, events
`@quikturn/logos/server`	Node.js	Buffer output, streaming, batch operations
`@quikturn/logos/element`	Browser	`<quikturn-logo>` custom element

Quick Start

import { logoUrl } from "@quikturn/logos";

// Zero-dependency URL builder — no network calls
const url = logoUrl("github.com", { size: 128, format: "webp" });
// → "https://logos.getquikturn.io/github.com?size=128&format=webp"

import { QuikturnLogos } from "@quikturn/logos/client";

const client = new QuikturnLogos({ token: "pk_live_xxx" });

const { url, blob, metadata } = await client.get("stripe.com", {
  size: 128,
  format: "webp",
});

// url is a blob: URL ready for <img> tags
document.querySelector("img").src = url;

// Clean up when done
client.destroy();

import { QuikturnLogos } from "@quikturn/logos/server";

const client = new QuikturnLogos({
  secretKey: process.env.QT_SECRET_KEY!,
});

// Single logo → Buffer
const { buffer, metadata } = await client.get("stripe.com");

// Batch fetch
for await (const result of client.getMany(["stripe.com", "github.com"])) {
  if (result.success) {
    console.log(result.domain, result.buffer.length);
  }
}

import { QuikturnProvider, QuikturnLogo } from "@quikturn/logos-react";

function App() {
  return (
    <QuikturnProvider token="pk_live_xxx">
      <QuikturnLogo domain="stripe.com" size={64} />
    </QuikturnProvider>
  );
}

Authentication

The SDK supports two key types:

Key Type	Prefix	Use In	Auth Method	Max Size
Publishable	`pk_` or `qt_`	Browser client, React, web component	`?token=` query param	800px
Secret	`sk_`	Server client only	`Authorization: Bearer` header	1200px

Never expose secret keys

Secret keys (sk_*) must only be used server-side. They are sent via the Authorization header and allow higher resolution logos (up to 1200px) and batch operations.

Logo Request Options

All clients accept the same options when requesting logos:

interface LogoRequestOptions {
  token?: string;              // API key (overrides client default)
  size?: number;               // Pixel width (default: 128, max: 800/1200)
  greyscale?: boolean;         // Desaturate to B&W
  theme?: "light" | "dark";    // Background variant
  format?: "png" | "jpeg" | "webp" | "avif";
}