directus-extension-unirate

A Directus extension bundle for the UniRate currency-exchange API. It adds two things to your Directus instance:

1. /unirate REST endpoint — proxies UniRate from your Directus server so the API key never reaches the browser. Hand your frontend /unirate/convert?to=EUR&amount=100 instead of exposing a key.
2. "UniRate Currency" Flow operation — a no-code Flows node that converts an amount, fetches a rate, or lists supported currencies inside any automation.

Zero runtime dependencies — pure native fetch. The API key lives only in your Directus environment.

Install

From the Directus Marketplace

In your Directus project, open Settings → Marketplace, search for UniRate, and install. (Marketplace availability depends on your hosting: self-hosted instances can install any extension; Directus Cloud lists sandboxed/registry extensions.)

Manually (self-hosted)

npm install directus-extension-unirate

Directus auto-discovers extensions in node_modules whose name starts with directus-extension-. Restart Directus after installing.

Configure the API key

Set the key in your Directus environment (.env, Docker env, etc.):

UNIRATE_API_KEY=your_key_here
# optional override (defaults to https://api.unirateapi.com)
# UNIRATE_API_BASE_URL=https://api.unirateapi.com

EXTENSION_UNIRATE_API_KEY is also accepted. Get a free key at unirateapi.com.

The /unirate endpoint

All routes are GET, return JSON, and keep your key server-side. They are mounted under /unirate on your Directus API.

| Route | Query params | Returns | |---|---|---| | /unirate/rates | from (default USD), to (optional) | { from, to, rate } or { from, rates } | | /unirate/convert | to (required), from (default USD), amount (default 1) | { from, to, amount, result } | | /unirate/currencies | — | { currencies: [...] } | | /unirate/vat | country (optional, ISO-3166 alpha-2) | UniRate VAT payload | | /unirate/historical | date (required, YYYY-MM-DD), from, to, amount | historical rate/result — Pro-gated |

# single rate
curl 'https://your-directus.example.com/unirate/rates?from=USD&to=EUR'
# → { "from": "USD", "to": "EUR", "rate": 0.92 }

# convert
curl 'https://your-directus.example.com/unirate/convert?to=JPY&amount=49.99'
# → { "from": "USD", "to": "JPY", "amount": 49.99, "result": 7847.1 }

# supported currencies
curl 'https://your-directus.example.com/unirate/currencies'
# → { "currencies": ["USD", "EUR", "GBP", ...] }

The /unirate/historical route requires a UniRate Pro plan. On the free tier it returns the upstream 403 unchanged.

Errors

Upstream UniRate errors are mapped to HTTP status + a JSON { "error": "..." } body: 400 invalid params, 401 bad/missing key, 403 Pro-only, 404 unknown currency, 429 rate-limited, 502 upstream/network failure. If the key is not configured the endpoint returns 503.

The "UniRate Currency" Flow operation

Add the UniRate Currency operation to any Flow. Configure:

• Operation — Convert amount, Get rate, or List currencies
• From currency — ISO 4217 code (default USD)
• To currency — ISO 4217 code (required for convert/rate)
• Amount — number (used by convert, default 1)

The operation's result is written to its data key for downstream steps:

// Convert amount
{ "from": "USD", "to": "EUR", "amount": 100, "result": 92.0 }

// Get rate (with To)
{ "from": "USD", "to": "EUR", "rate": 0.92 }

// List currencies
{ "currencies": ["USD", "EUR", "GBP", ...] }

A missing key or an upstream failure throws, routing the Flow down its reject path so you can handle it (notify, retry, fall back).

Example uses: stamp a converted price_eur onto an item on create, post a daily FX snapshot to Slack, or validate a currency code against the live supported list.

Reusing the typed client

The bundle also exports the standalone, dependency-free TypeScript client used under the hood — handy in custom hooks or other extensions:

import { UniRateClient, ProRequiredError } from "directus-extension-unirate/client";

const client = new UniRateClient({ apiKey: process.env.UNIRATE_API_KEY! });
const eur = await client.convert("EUR", 100, "USD");

Security

• The UniRate API key is read only from the Directus server environment and is never sent to the browser or included in any response.
• The package ships zero runtime dependencies (native fetch), built with plain tsc — no bundler/transpiler tree pulled into your install.
• Published to npm with provenance (npm attestations).

Development

npm install
npm run typecheck
npm test          # vitest mock suite
npm run build     # tsc → dist/

CI runs typecheck + tests + build on Node 20 and 22.

Other UniRate clients

UniRate ships official client libraries and framework integrations across the ecosystem. The repos below are all maintained under the UniRate-API org.

• Languages: Python · Node.js / TypeScript · Go · Rust · Java · Ruby · PHP · .NET · Swift
• Web frameworks: Next.js · Nuxt · SvelteKit · NestJS · Django / Wagtail · Django REST · FastAPI · Flask · React · Vue · tRPC
• Static-site generators: Astro · Eleventy · Hugo
• CMS / headless: Directus
• Data / orchestration: Airflow · dbt · LangChain
• Workflow / no-code: n8n · Google Sheets · MCP server
• Editors / tools: VS Code · Obsidian
• Specialty bridges: RubyMoney · Laravel Money · NodaMoney (.NET)

Get a free API key at unirateapi.com.

License

MIT © 2026 UniRate API