API Reference

This reference covers every endpoint in the Tolinku REST API. All endpoints are JSON-based unless otherwise noted.

Base URL

https://your-app.tolinku.com/v1/api

Replace your-app.tolinku.com with your Appspace’s domain (subdomain or custom domain).

Authentication

Include your API key in every request via the X-API-Key header:

curl -H "X-API-Key: tolk_sec_your_secret_key" \
  https://your-app.tolinku.com/v1/api/analytics/overview

See Authentication for details on key types and scopes.

Request format

• All request bodies must be JSON with Content-Type: application/json.
• Query parameters use standard URL encoding.
• Dates use ISO 8601 format (e.g. 2026-01-15).

Response format

All successful responses return JSON. The shape varies by endpoint but follows consistent patterns:

// Single resource
{ "referral_code": "ABC123", "status": "pending" }

// Collection
{ "banners": [ ... ] }

// Action confirmation
{ "ok": true }

Error format

All errors return a JSON object with an error field:

{
  "error": "Human-readable error message"
}

Plan enforcement errors include a code field:

{
  "error": "This feature requires a paid plan",
  "code": "FEATURE_GATED"
}

Code	Meaning
FEATURE_GATED	The feature is not available on the free tier
USAGE_EXCEEDED	The Appspace has exceeded its plan’s usage limits
APPSPACE_FROZEN	The Appspace is frozen (billing issue)

Rate limits

All /v1/api/ endpoints share a rate limit of 1,000 requests per minute per IP address. Exceeding this limit returns HTTP 429:

{ "error": "Too many requests. Please slow down." }

Standard RateLimit-* headers are included in every response.

Usage warnings

When your Appspace reaches 80% of its plan’s click or API call limit, responses include an X-Usage-Warning header with the current usage percentage.

Available resources

Authentication API key types, scopes, and request headers.

Deep Links Resolve routes, claim deferred links, and collect device signals.

Analytics Query metrics, export data, and track custom events.

Referrals Create referral codes, track milestones, and claim rewards.

Banners Fetch active smart banners for in-app display.

Messages Fetch in-app messages and render content.

Ecommerce Track purchases and revenue. Query attribution, cohorts, and product metrics.

Audiences Check segment membership and list users.