Dragonfly Docs

Dragonfly is an OpenAI-compatible AI access layer with market routing. Keep one API surface while applying routing rules, pricing controls, and seller selection.

Chat, embeddings, speech, models, buyer keys, and request tracing are documented in one place.

OpenAI SDK

Switch the base URL and keep the same client shape.

Market Routing

Apply seller, price, latency, and provider constraints.

Request Tracing

Every response includes x-request-id. Query trade details via GET /v1/generation?id=.

Buyer Keys

Manage access keys and routing profiles from the dashboard.

Speech + Embeddings

Use /audio/speech and /embeddings on the same base URL.

What is different in Dragonfly

Dragonfly adds market routing and execution controls on top of an OpenAI-compatible interface, instead of acting as a plain model gateway.

Quick Start

Make your first request in under a minute.

1. Create an account

2. Create access key + routing profile

Go to Dashboard → Keys and create an API key.

3. Make your first matched request

Use any OpenAI-compatible SDK — change one line.

from openai import OpenAI

client = OpenAI(
    base_url="https://dragonfly-api.com/v1",
    api_key="sk-df-YOUR_KEY",
)

resp = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "Hello"}],
)
print(resp.choices[0].message.content)

Authentication

All API requests must include a valid API key in the Authorization header.

Your API keys start with sk-df-. Keep them secret — do not expose them in client-side code.

Authorization: Bearer sk-df-YOUR_KEY

Manage your keys →

API Keys

API keys (sk-df-*) authenticate your inference requests to /v1/* endpoints. Create and manage them via the dashboard or the /api/keys endpoints below.

Key shown once

The full sk-df-... key is only returned at creation. After that, only a hint (e.g. sk-df-c7a5...d3a3) is stored.

POST /api/keys

Returns the raw key once — store it securely.

POST/api/keys

Parameter	Type	Required	Description
name	string	No	Human-readable label for the key.
key_group	string	No	Logical grouping for usage tracking. Lowercase alphanumeric, dashes, underscores. Default: "default".
monthly_budget_cents	integer	No	Monthly spend cap in US cents. e.g. 500 = $5.00 limit per month. null to remove the cap.
routing_profile_id	uuid	No	UUID of a routing profile to bind. Omit to use the default profile.
ip_whitelist	array	No	List of CIDR ranges allowed to use this key. Empty = allow all.
ip_blacklist	array	No	List of CIDR ranges blocked from using this key.

curl https://dragonfly-api.com/api/keys \
  -H "Authorization: Bearer YOUR_JWT_OR_MGMT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production",
    "key_group": "prod",
    "monthly_budget_cents": 5000
  }'

Response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "production",
  "key_group": "prod",
  "routing_profile_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "key": "sk-df-a1b2c3d4e5f6..."
}

GET /api/keys

Returns all keys for the authenticated user. The raw key is never returned after creation.

GET/api/keys

PATCH /api/keys/:id

Update budget, routing profile, or IP controls on an existing key.

PATCH/api/keys/:id

Parameter	Type	Required	Description
monthly_budget_cents	integer\|null	No	Monthly spend cap in US cents. e.g. 500 = $5.00 limit per month. null to remove the cap.
routing_profile_id	uuid\|null	No	UUID of a routing profile to bind. Omit to use the default profile.
ip_whitelist	array	No	List of CIDR ranges allowed to use this key. Empty = allow all.
ip_blacklist	array	No	List of CIDR ranges blocked from using this key.

DELETE /api/keys/:id

Revokes the key immediately. In-flight requests using this key are not affected.

DELETE/api/keys/:id

Management Keys

Management keys authenticate programmatic account operations — creating buyer keys, reading usage, or managing seller listings — without exposing your dashboard credentials.

Scopes control what the key can do:

buyer — Read and manage buyer API keys and routing profiles.
seller — Read and manage seller listings and earnings.
full — All buyer and seller operations.

Using management keys

Management keys authenticate to /api/mgmt/* endpoints using the same Authorization: Bearer sk-df-... header as buyer keys. They do not work on /v1/* inference endpoints.

POST /api/management-keys

Returns the raw key once. The scope cannot be changed after creation.

POST/api/management-keys

Parameter	Type	Required	Description
name	string	Yes	Human-readable label.
mgmt_scope	string	Yes	"buyer", "seller", or "full". Cannot be changed after creation.
expires_at	datetime	No	ISO 8601 datetime for automatic expiry. Omit for no expiry.

curl https://dragonfly-api.com/api/management-keys \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ci-pipeline",
    "mgmt_scope": "buyer"
  }'

Response

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "name": "ci-pipeline",
  "mgmt_scope": "buyer",
  "key_hint": "sk-df-b2c3...e5f6",
  "key": "sk-df-b2c3d4e5f6a1..."
}

GET /api/management-keys

Returns all management keys for the authenticated user.

GET/api/management-keys

DELETE /api/management-keys/:id

Revokes the key immediately.

DELETE/api/management-keys/:id

Buyer Features

Buyer accounts focus on secure inference access, spend controls, and routing policy management.

Buyer API keys

Create, rotate, revoke, and organize buyer keys with key groups, monthly budgets, and IP allow or block lists.

Routing profiles

Configure cost-first, balanced, reliability-first, quality-first, or custom behavior with provider filters, price ceilings, latency targets, throughput limits, and fallback rules.

Spend and usage

Track balance, transactions, aggregate usage, daily usage, and per-key cost directly from the dashboard.

Integration workflow

Browse the model catalog, copy OpenAI-compatible snippets, bind a routing profile to a key, and validate requests in Playground.

Core buyer endpoints

GET  /api/keys
POST /api/keys
PATCH /api/keys/:id
DELETE /api/keys/:id

GET  /api/routing/profiles
POST /api/routing/profiles
PATCH /api/routing/profiles/:id

GET  /api/usage
GET  /api/usage/by-key
GET  /api/usage/daily
GET  /api/billing/balance

Buyer auth boundary

Use buyer API keys on /v1/* inference routes. Use management keys only when you need account automation outside the dashboard.

Seller Features

Seller accounts supply capacity into the market and manage listing health, payouts, and compliance from one console.

Provider pool keys

Listings and pricing

Create, edit, pause, and delete listings with model selection, rpm caps, concurrency, payout floors, cache pricing, multiplier pricing, and auto-follow price controls.

Admission and contracts

Inspect listing contracts and check history, run admission probes, confirm reviewed pricing, reverify degraded contracts, and unsuspend contracts after recovery.

Earnings and reserves

Review payout balances, locked earnings, reserves, monthly summaries, timeseries performance, and settlement history.

Operations visibility

Monitor market health, routing activity, trade reviews, and relay or provider health to keep supply schedulable.

Core seller endpoints

GET  /v1/pool/providers
GET  /v1/pool/keys
POST /v1/pool/keys
DELETE /v1/pool/keys/:id

GET  /v1/market/listings
POST /v1/market/listings
PATCH /v1/market/listings/:id
DELETE /v1/market/listings/:id
POST /v1/market/listings/:id/confirm-price

GET  /v1/market/listings/:id/contracts
GET  /v1/market/contracts/:id/checks
POST /v1/market/contracts/:id/reverify
POST /v1/market/contracts/:id/unsuspend
POST /v1/market/listings/:id/probe
GET  /v1/market/listings/:id/probe-runs

GET  /v1/market/earnings
GET  /v1/market/earnings/summary
GET  /v1/market/earnings/timeseries
GET  /v1/market/earnings/monthly

Seller lifecycle

A seller flow usually starts with provider key registration, then listing creation, admission checks, active market routing, and finally earnings settlement.