// documentation

Using the flye.win API

Every API in the catalog shares the same authentication, error format, and limits. This page covers what they have in common; each API has its own page with endpoints, parameters, and examples.

Quick start

01
Create an account
Email and password, or Google. Create an account.
02
Generate an API key
Go to Dashboard → Keys. The full key is shown only once, so store it in a secrets manager.
03
Activate a plan on the API
Every API has a Free plan. Open the API in the catalog and activate it.

Make your first request

$ export FLYE_KEY="flye_sk_…"
$ curl https://flye.win/v1/utils/uuid -H "Authorization: Bearer $FLYE_KEY"

Authentication

Send your key in either of two headers. Keys start with flye_sk_ and work for every API you subscribe to.

Authorization: Bearer flye_sk_…
# or
X-API-Key: flye_sk_…

Keys are server secrets. Don't put them in mobile apps or the browser; call flye.win from your backend. Key leaked? Revoke it in the dashboard. It takes effect immediately.

Requests and responses

—Base: https://flye.win/v1/<api>
—Request and response bodies are UTF-8 JSON (Content-Type: application/json).
—Success returns 2xx with the object directly, with no envelope.
—CORS is open, but remember: your key should not reach the browser.

Errors

Every error has the same format. Use code in your code; message is for humans and may change.

{
  "error": {
    "code": "quota_exceeded",
    "message": "Your plan's monthly quota is used up."
  }
}

status	code	when
400	invalid_param	A parameter has an invalid value.
400	missing_param	A required parameter is missing.
401	missing_api_key	No key was sent.
401	invalid_api_key	The key doesn't exist or was revoked.
403	no_subscription	No active plan for the API you called.
404	not_found	The route doesn't exist.
429	rate_limited	Per-minute limit reached. Respect `Retry-After`.
429	quota_exceeded	Monthly quota used up. It renews on the 1st or when you upgrade.
401	key_expired	The key is past the expiry set in your dashboard.
403	key_wrong_product	The key is restricted to another product.
403	ip_not_allowed	The IP isn't on the key's allowed list.
429	too_many_invalid_keys	Too many invalid keys from this IP. Check your key and wait a minute.
503	overloaded	The server is under heavy load. Doesn't use quota. Try again after `Retry-After`.
500	internal_error	Our fault. You can retry with backoff.

Limits and quotas

Each plan sets two limits, counted per account and per API (not per key):

—Rate limit — requests per minute, in a fixed 60-second window.
—Quota — requests per calendar month, reset on the 1st.

Per end-user limit

Plans with this model, like Scale, have no monthly cap. Send X-End-User-Id with a stable id for the user on your platform, preferably a hash, and the per-minute limit applies to each user: if one overdoes it, only they get a 429 with the code end_user_rate_limited, and everyone else carries on.

Calls without the header share the account limit. On any other plan the header is ignored. To protect against loops, each account has a ceiling of 60,000 requests per minute, which returns the code platform_protection.

header	meaning
X-RateLimit-Limit	Requests allowed per minute.
X-RateLimit-Remaining	Remaining in the current window.
X-RateLimit-Reset	Seconds until the window resets.
X-RateLimit-Scope	Who the limit applies to: `account` or `end-user`.
X-Quota-Limit	The plan's monthly quota (omitted if unlimited).
X-Quota-Remaining	Requests remaining this month.
Retry-After	Sent with a rate limit 429.

Versioning

The version is in the path (/v1). Within a version we only make compatible changes: new endpoints, new optional fields, and new error codes. Ignore fields you don't recognize. Breaking changes go to /v2, with a period where both versions run side by side.

Status

GET /v1/status is public, needs no key, and doesn't use quota. It's useful for health checks. History is on the status page.

curl https://flye.win/v1/status