Authentication

Every API request is authenticated with an API key sent in the x-api-key request header. Keys are not accepted in the URL, the query string, the Authorization header or the body. The base URL is https://deeplinknow.com/api/v1.

Key types

Each app has its own keys, and a key only ever acts on the app it belongs to. There are two types:

Type	Format	Endpoints	Where to use it
Public	`dln_pub_…`	`/api/v1/sdk/*` (init, match, referrer-lookup, fingerprint, unfurl)	Inside your mobile app, via the SDKs. Safe to ship.
Private	`dln_priv_…`	`/api/v1/deeplinks`, `/api/v1/campaigns`, `/api/v1/analytics`	Your own server only. Never put it in an app, a web page or a public repository.

Calling an endpoint with the wrong key type returns 401 with a message naming the key type it needs. Keys that start with dln_ and were created before key types existed work as public keys.

Getting and managing keys

Keys are issued per app: creating an app in the dashboard creates one public key and one private key for it.
Your public key isn't secret (it ships inside your app), so the dashboard always shows it. A private key is shown once, when it is created or regenerated: DeepLinkNow stores only a SHA-256 hash of it, so the dashboard shows a masked hint after that.
If you lose a private key, or a key leaks, regenerate it from the API Keys page in the dashboard. You choose when the old key stops working: a public key keeps working until you revoke it (so installed apps don't break), a private key for 24 hours by default, or either one immediately if it leaked. An expired key gets 401 API key has expired.

Using your key

A server-side call to the management API with your private key:

curl "https://deeplinknow.com/api/v1/deeplinks?limit=20" \
  -H "x-api-key: dln_priv_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

const response = await fetch("https://deeplinknow.com/api/v1/deeplinks", {
  method: "POST",
  headers: {
    "x-api-key": process.env.DLN_PRIVATE_KEY!, // dln_priv_...
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ targetUrl: "https://example.com/product/123" }),
});

The SDKs send your public key for you; you pass it once to initialize.

Test key

The key test_api_key is a demo key you can use to try an SDK or the API before you create an app. It works on every keyed endpoint, returns mock responses, and never reads or writes real data.

Rate limits and quotas

SDK deferred-link calls (sdk/init, sdk/match, sdk/referrer-lookup) are not rate limited and don't count toward a request quota. They are billed by monthly active users.
The management API (/api/v1/deeplinks, /api/v1/campaigns, /api/v1/analytics) is for paid plans. On the free Developer plan, private-key requests return 403 API access requires a paid plan. Upgrade your account at https://deeplinknow.com/dashboard/settings to use the management API..
Other keyed endpoints are rate limited per key, by plan: Startup 600 requests per minute, Growth 1,200 requests per minute, Enterprise custom. On the Developer plan only sdk/fingerprint and sdk/unfurl are metered, at 600 requests per minute.
Management API calls count toward your plan's monthly API request quota (Startup 10,000, Growth 50,000, Enterprise unlimited). The quota is per account: calls from all of your apps' private keys add up, and regenerating a key does not reset it. It resets at the start of each UTC month. sdk/fingerprint and sdk/unfurl don't count toward it.
Creating deep links through the API is limited by your plan's link allowance, which counts distinct paths (the part of the link before ?) across all of your apps. A new query string on a path you already have doesn't use up the allowance.
Exceeding a limit returns 429. The per-minute and monthly limits include a Retry-After header in seconds.

Error responses

Errors are JSON with an error message and, for validation failures, a details array:

{ "error": "Invalid API key" }

Status	Meaning
400	Malformed JSON or invalid parameters
401	Missing, unknown or inactive key, or the wrong key type
403	Account not active, no credits, the management API on the free plan, or a feature that needs a paid plan
404	Not found (including resources that belong to another app)
429	Rate limit, monthly quota or deep link allowance exceeded