API Overview

The Fyralynx REST API gives Publisher and Enterprise tier creators programmatic access to the same intelligent affiliate routing engine that powers the browser extension. Create routed links, retrieve full CRC traces, query merchant EPC data, access click analytics, and - on Enterprise - receive real-time webhook events.

Base URL

All API endpoints are served from:

https://api.fyralynx.com/v1

Every request must use HTTPS. HTTP requests are rejected with a redirect to the HTTPS equivalent.

Authentication

All endpoints except GET /health require a Bearer API key in the Authorization header:

http

Authorization: Bearer flx_live_sk_1234567890abcdefghijklmnopqrstuvwxyz

API keys are generated in Settings → API Keys in the Fyralynx dashboard. Each key is scoped to a single creator account. You can maintain multiple active keys per account (e.g. one per environment).

See the Authentication guide for complete details on key generation, security best practices, and error handling.

Plan requirements

Plan	API Access
Free	None - no API access
Creator	None - no API access
Pro	None - no API access
Publisher	All endpoints except `POST /links/bulk` and webhooks
Enterprise	All endpoints including `POST /links/bulk`, webhooks, and SLA

Calling an endpoint beyond your plan's access level returns HTTP 403 with code PUBLISHER_TIER_REQUIRED or ENTERPRISE_TIER_REQUIRED.

Rate Limits

Rate limits are applied per API key in a sliding 60-second window.

Plan	Requests / minute
Publisher	60
Enterprise	600

Every API response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests allowed per 60-second window.
`X-RateLimit-Remaining`	Requests remaining in the current window.
`X-RateLimit-Reset`	Unix timestamp when the window resets.

When the limit is exceeded, the API returns HTTP 429 with a Retry-After header. See the Rate Limits guide for retry strategies and patterns.

Versioning

This is API v1. The version prefix /v1 is part of every endpoint URL.

Backward-compatible changes (new optional request fields, new optional response fields, new endpoints) are deployed without a version bump and documented in the API changelog.

Breaking changes are released under a new version prefix (e.g. /v2). The previous version remains available for a minimum of 12 months after a new version is published.

Request Format

All request bodies must be JSON with Content-Type: application/json:

http

POST /v1/links HTTP/1.1
Host: api.fyralynx.com
Authorization: Bearer flx_live_sk_…
Content-Type: application/json

{
  "url": "https://www.amazon.com/dp/B0CRMZHDG4",
  "preset": "auto",
  "title": "Sony WH-1000XM5 Headphones"
}

Response Format

All successful responses wrap the payload in a data key:

json

{
  "data": {
    "id": "01HX4Z9Y3ABCDEF1234567890AB",
    "routeUrl": "https://go.fyralynx.com/r/abc123",
    "merchantId": "amazon",
    "networkId": "Impact",
    "region": "US",
    "confidence": 87,
    "normalizedEpcUsd": 0.043
  }
}

Paginated responses include a pagination key alongside data:

json

{
  "data": [ … ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 347,
    "totalPages": 18,
    "hasNextPage": true,
    "hasPrevPage": false
  }
}

Error Format

All error responses use a consistent structure:

json

{
  "code": "ERROR_CODE",
  "message": "Human-readable description of the error.",
  "requestId": "01HX4Z9Y3ABCDEF1234567890AB"
}

Validation errors include an additional errors array:

json

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed.",
  "requestId": "01HX4Z9Y3ABCDEF1234567890AB",
  "errors": [
    {
      "field": "url",
      "message": "Must be a valid HTTPS URL from a supported merchant domain."
    },
    {
      "field": "preset",
      "message": "Must be one of: auto, link-in-bio, long-form."
    }
  ]
}

Always log the requestId from any error response - include it in any support request.

HTTP status codes

Status	When it occurs
`200 OK`	Successful read (`GET`, `PATCH`).
`201 Created`	Successful resource creation (`POST /links`, `POST /links/bulk`).
`204 No Content`	Successful deletion (`DELETE /links/{id}`).
`400 Bad Request`	Malformed JSON or unrecognised query parameter.
`401 Unauthorized`	Missing or invalid `Authorization` header.
`403 Forbidden`	Valid key but insufficient plan tier, or IP allowlist violation.
`404 Not Found`	Resource with given ID does not exist (or was deleted).
`422 Unprocessable Entity`	Well-formed request that fails semantic validation (e.g. unsupported merchant domain).
`429 Too Many Requests`	Rate limit exceeded. Check `Retry-After` header.
`500 Internal Server Error`	Unexpected worker error. The original URL is still accessible if this affects the edge redirector.
`503 Service Unavailable`	Worker is temporarily unavailable. Rare - Cloudflare Workers SLA is 99.9%+.

Error codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid `Authorization` header, or key has been revoked.
`PUBLISHER_TIER_REQUIRED`	403	Action requires Publisher or Enterprise plan.
`ENTERPRISE_TIER_REQUIRED`	403	Action requires Enterprise plan (e.g. `POST /links/bulk`, webhooks).
`IP_NOT_ALLOWLISTED`	403	Request IP is not in the Enterprise key's IP allowlist.
`NOT_FOUND`	404	Requested resource does not exist.
`BAD_REQUEST`	400	Request body could not be parsed as JSON or has an unknown top-level key.
`VALIDATION_ERROR`	422	Request is well-formed but fails semantic validation. See `errors` array.
`UNSUPPORTED_MERCHANT`	422	URL domain is not a supported Fyralynx merchant. Link created with `passthrough: true`.
`RATE_LIMIT_EXCEEDED`	429	Per-key rate limit exceeded. Honour `Retry-After`.
`CLICK_QUOTA_EXCEEDED`	403	Monthly click quota reached (Free tier hard cap).
`DUPLICATE_URL`	422	Duplicate URL detected in a bulk create request.
`INTERNAL_SERVER_ERROR`	500	Unexpected error. Include `requestId` when contacting support.

Routing Presets

All link creation and routing endpoints accept a preset parameter that adjusts the weights of signals in the EPC scoring formula.

Preset	Value	Description
Auto	`auto`	Default/balanced. Equal weight across all signals. Best for most use cases.
Link-in-Bio	`link-in-bio`	Mobile-first. Boosts device bias signal (+20%), lowers redirect depth tolerance, fast geo-fallback. Best for Instagram, TikTok, YouTube channel links.
Long-form	`long-form`	EPC-aggressive. Prioritises deep-link bonus and raw EPC. Higher redirect tolerance. Best for product review articles and comparison posts.

Presets are advisory - the routing engine always produces the best route within the preset's signal weights. The winning candidate is never changed to a strictly worse route.

CRC Trace

Every POST /links, GET /links/{id}, and POST /route response includes a crcTrace object - the complete, auditable routing decision trace.

json

{
  "crcTrace": {
    "winner": {
      "merchantId": "amazon",
      "networkId": "Impact",
      "region": "US",
      "routeScore": 0.0487,
      "normalizedEpcUsd": 0.043,
      "confidence": 87
    },
    "alternatives": [
      {
        "merchantId": "amazon",
        "networkId": "CJ",
        "region": "US",
        "routeScore": 0.0451,
        "normalizedEpcUsd": 0.039,
        "confidence": 82,
        "whyNotChosen": "Impact scored +0.0036 higher due to private deal override (+8%) applied to this network."
      },
      {
        "merchantId": "amazon",
        "networkId": "Impact",
        "region": "GB",
        "routeScore": 0.0389,
        "normalizedEpcUsd": 0.034,
        "confidence": 79,
        "whyNotChosen": "Region mismatch penalty - visitor is US, GB storefront applied -0.08 region penalty."
      }
    ],
    "signals": [
      { "name": "epc_base",       "value": 0.035,  "label": "Base EPC (Impact/Amazon US)",   "source": "essential" },
      { "name": "trend",          "value": 0.08,   "label": "Short-term EPC trend (EWMA)",   "source": "essential" },
      { "name": "fx",             "value": 1.0,    "label": "FX rate (USD base, no conversion)", "source": "essential" },
      { "name": "device",         "value": 0.0,    "label": "Device bias (desktop)",          "source": "essential" },
      { "name": "deeplink",       "value": 0.12,   "label": "Deep-link validated",            "source": "essential" },
      { "name": "region_match",   "value": 0.08,   "label": "Region match (US visitor → US storefront)", "source": "essential" },
      { "name": "health",         "value": -0.0,   "label": "Link health (depth 1, no issues)",  "source": "essential" },
      { "name": "refund",         "value": -0.05,  "label": "Refund rate estimate (5%)",      "source": "essential" },
      { "name": "offer",          "value": 0.0,    "label": "No active offer for this merchant", "source": "essential" },
      { "name": "net_trust",      "value": 0.02,   "label": "Network trust adj. (Impact: +2%)", "source": "essential" },
      { "name": "category",       "value": 1.05,   "label": "Category multiplier (Electronics)", "source": "essential" },
      { "name": "cod",            "value": 1.0,    "label": "COD factor (US - not applicable)", "source": "essential" },
      { "name": "ua_penalty",     "value": -0.0,   "label": "UA/referrer penalty (none)",     "source": "essential" },
      { "name": "utm",            "value": 0.03,   "label": "UTM preservation (+3%)",         "source": "essential" },
      { "name": "availability",   "value": -0.0,   "label": "Availability (US ships to US)",  "source": "essential" },
      { "name": "deal",           "value": 0.08,   "label": "Private deal override (+8%)",    "source": "creator" }
    ],
    "scoringFormula": {
      "intermediateScore": 0.0443,
      "confidenceFactor": 1.10,
      "finalScore": 0.0487
    }
  }
}

The CRC trace is the foundation of Fyralynx's transparency guarantee. Every routing decision is fully auditable. Signal labels include plain-English explanations identical to what is shown in the Creator Routing Console in the browser extension.

Signal sources

Source	Meaning
`essential`	Derived from static merchant profiles and local KV data. Always available. No live API calls.
`enrichment`	Derived from live affiliate network APIs (when credentials are configured). Best-effort - may not always be available.
`creator`	Derived from the creator's declared preferences or private deal overrides.

Pagination

List endpoints accept page (1-based, default: 1) and limit (1-100, default: 20) query parameters.

http

GET /v1/links?page=2&limit=50

Response:

json

{
  "data": [ … ],
  "pagination": {
    "page": 2,
    "limit": 50,
    "total": 347,
    "totalPages": 7,
    "hasNextPage": true,
    "hasPrevPage": true
  }
}

There is no cursor-based pagination in v1. For large result sets (> 10,000 items), use date range filters to scope requests.

Merchant IDs

Merchant IDs are lowercase, hyphenated strings. A selection:

Merchant	`merchantId`
Amazon (all regions)	`amazon`
Flipkart	`flipkart`
Myntra	`myntra`
Nykaa	`nykaa`
Jumia	`jumia`
Noon	`noon`
Lazada	`lazada`
Shopee	`shopee`
Mercado Libre	`mercadolibre`
Takealot	`takealot`
ASOS	`asos`
Zalando	`zalando`
Temu	`temu`

Use GET /v1/merchants to retrieve the full list of all 35 supported merchant IDs.

Network IDs

Network	`networkId`
Commission Junction	`CJ`
Awin	`Awin`
Impact Radius	`Impact`
Admitad	`Admitad`
Cuelinks (India-focused)	`Cuelinks`
Rakuten Advertising	`Rakuten`
Involve Asia (SE Asia)	`InvolveAsia`

Supported Currencies

The Fyralynx EPC engine normalises all values to USD internally. The following currencies are supported for display and billing:

USD · GBP · EUR · INR · CAD · AUD · JPY · SGD · MYR · THB · IDR · PHP · AED · SAR · EGP · NGN · ZAR · BRL · MXN · ARS · KRW · TWD · VND

CORS

The API sets Access-Control-Allow-Origin: * for GET /health only. All authenticated endpoints restrict CORS to *.fyralynx.com and any additional origins declared in your Enterprise webhook configuration. Browser-based API calls from third-party origins are not supported and not recommended - always call the API from your server.

OpenAPI Specification

The complete OpenAPI 3.1 specification is available at:

Browsable: docs.fyralynx.com/openapi.yaml
Raw YAML: https://docs.fyralynx.com/openapi.yaml

The spec is the authoritative source for all request/response schemas, enum values, and validation constraints. It is generated automatically from TypeScript types in the API worker source.

API Overview ​

Base URL ​

Authentication ​

Plan requirements ​

Rate Limits ​

Versioning ​

Request Format ​

Response Format ​

Error Format ​

HTTP status codes ​

Error codes ​

Routing Presets ​

CRC Trace ​

Signal sources ​

Pagination ​

Merchant IDs ​

Network IDs ​

Supported Currencies ​

CORS ​

OpenAPI Specification ​

See Also ​

API Overview

Base URL

Authentication

Plan requirements

Rate Limits

Versioning

Request Format

Response Format

Error Format

HTTP status codes

Error codes

Routing Presets

CRC Trace

Signal sources

Pagination

Merchant IDs

Network IDs

Supported Currencies

CORS

OpenAPI Specification

See Also