Building a connector

Want StyleRef inside a tool we haven’t reached? The API the ComfyUI nodes use is public, documented, and stable. This page explains what to build against.

The contracts you can depend on

Three published surfaces. Everything else is an implementation detail that may change.

The OpenAPI document evolves additively — new fields and endpoints appear, existing ones don’t change shape or disappear.

The core loop

Most connectors are one of these, or both:

Read — anonymous, no account:

1. GET /api/v1/styles?query=… — search the public gallery
2. GET /api/v1/styles/{ref}?format=… — fetch a style compiled for a target

Write — needs a token:

1. POST /api/v1/extractions — upload an image to extract a style from
2. GET /api/v1/extractions/{id} — poll, optionally saving to the user’s library
3. GET /api/v1/me/styles — list the user’s own styles

A read-only connector is a legitimate and useful thing to ship. Start there.

Leave prompt compilation on the server

The single most important design rule.

GET /styles/{ref}?format=flux returns the style compiled for FLUX; format=diffusion returns tag-weighted text for SDXL and SD1.5; format=default returns natural-language prose. Ask for the format you need rather than transforming the style yourself.

Two reasons. Prompt phrasing is where most of StyleRef’s work lives, and it improves — a connector that consumes compiled output gets those improvements without a release, while one that builds its own prompt text is frozen at the day it was written. And a style should mean the same thing everywhere; a connector that rewrites prompts creates a dialect only its users see.

Use ?raw=1 when the text goes straight to a model. It omits the markdown header and attribution line, which would otherwise be encoded as literal tokens. Surface attribution separately in your UI.

Use format=json when you need structured fields — palette hexes, lighting, guardrails — rather than prose.

Authentication

Anonymous requests need nothing. Rate limits apply per IP.

For authenticated calls, StyleRef runs an OAuth 2.1 authorization server with PKCE and dynamic client registration. See authentication.

Three things worth doing the way existing connectors do:

Store tokens in the shared credentials file. ~/.config/styleref/credentials.json (or $XDG_CONFIG_HOME), owner-only permissions. The CLI and the ComfyUI nodes both use it, so a user signs in once for all of them.

Honor STYLEREF_TOKEN. An environment variable that overrides stored credentials. This is not a fallback — it is the only path that works when your tool runs on a remote or headless machine, where a browser-based flow cannot complete. Document it prominently.

Degrade to anonymous when a session dies. If a refresh fails, keep public features working rather than blocking everything behind a re-login.

Identify your client

Send a X-StyleRef-Client header naming your connector:

X-StyleRef-Client: comfyui

It tells us which surfaces are actually used, which is how connectors get prioritized.

Handling errors well

The API writes its error messages for humans. 402 (out of credits) and 401 (sign-in needed) carry a message field and a relevant URL.

Render those messages verbatim. They’re maintained centrally and stay accurate as plans change; a paraphrase in your client will drift.

Other cases worth handling explicitly:

• 429 — respect Retry-After. Cache fetched styles so re-runs don’t re-fetch.
• Never retry a POST /extractions — each one spends a credit. Retry GETs freely.
• Uploads cap at 8 MB. Resize for transport before uploading, but don’t downscale aggressively — the server handles model-sizing itself, and a small upload permanently limits the reference image stored with the style.

Licensing and publishing

Connectors we maintain are MIT, in their own public repos. We suggest the same for community connectors, but it’s your call.

Building something? Open an issue  or email hello@styleref.io — we’ll help, and we’ll list it here.

Reference implementations

Both are small, dependency-free, and worth reading before starting:

• styleref-comfyui — Python. OAuth loopback, headless detection, gallery search, per-target compilation.
• styleref CLI — Node. The same flows, no UI framework in the way.