Skip to content
Back to Docs API Secure integration

API: integrate link creation & analytics

Automate link creation, rule configuration, and analytics retrieval. Use API keys for authentication and permission-scoped access.

This is a safe “public” reference. Map endpoints/fields to your actual backend.

Quick table of contents
Create account Read Getting started

Authentication (API key)

Generate API keys in the dashboard and display them only once. Send the key via headers.

Sample headers
Authorization: Bearer YOUR_API_KEY
Accept: application/json
  • Never hardcode API keys in the frontend.
  • Rotate keys periodically and revoke on suspicion.
  • Scope permissions by user/project if available.

Base URL & versioning

Version your API to avoid breaking integrations when you ship changes.

Suggested base URL
https://1linkad.com/api/v1
  • Return consistent JSON: ok/data/error.
  • Standardize error codes/messages for easier debugging.

Rate limits & common errors

Set rate limits to protect your system and prevent abuse.

  • 429429 Too Many Requests: over limit.
  • 401401 Unauthorized: missing/invalid API key.
  • 403403 Forbidden: insufficient permissions.
  • 422422 Validation error: invalid payload.
  • 500500: internal error (include trace_id).
  • Expose X-RateLimit-* headers for clients.
  • Always include trace_id in error responses for fast support.

Endpoint list (reference)

These endpoints are reference examples—map them to your actual backend.

Links
POST /links
Create a link (domain, slug, target_url, rules, tracking).
GET /links
List links (paging, filters).
GET /links/{id}
Get link details.
PATCH /links/{id}
Update link/rules/tracking.
DELETE /links/{id}
Delete a link.
Domains
POST /domains
Add a domain.
GET /domains
List domains.
POST /domains/{id}/verify
Verify DNS.
POST /domains/{id}/ssl
Enable SSL (if supported).
Analytics
GET /analytics/links/{id}
Link analytics over time (clicks, device, country, referrer).
GET /analytics/campaigns
Aggregate by UTM campaign (optional).

cURL examples

Reference examples for creating a link and fetching analytics.

Create link (POST /links)
curl -X POST "https://1linkad.com/api/v1/links" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "go.example.com",
    "slug": "summer-sale",
    "target_url": "https://example.com/landing",
    "tracking": true,
    "redirect_code": 302,
    "rules": [
      {"if": {"country": ["VN"], "device": ["mobile"]}, "to": "https://example.com/vn-m"},
      {"if": {"country": ["VN"]}, "to": "https://example.com/vn"}
    ],
    "fallback_url": "https://example.com/default"
  }'
Fetch analytics (GET /analytics/links/{id})
curl -X GET "https://1linkad.com/api/v1/analytics/links/123?from=2026-02-01&to=2026-02-11" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
  • Always validate target_url and protect against SSRF in backend.
  • If rules are complex, provide a dry-run endpoint to test matching.

Webhook/Postback (optional)

If you need to send events back to your system (conversion/click), use webhook/postback.

  • Sign payloads with HMAC to authenticate events.
  • Retry with backoff on 5xx responses.
  • Allow users to enable/disable per project.

Integration security checklist

Minimum security checklist for safe APIs:

  • Rate limit by API key + IP.
  • Audit logs: who created/updated/deleted links and when.
  • URL validation (SSRF protection), block dangerous schemes (file://, gopher://…).
  • CORS only when truly needed.
  • Return trace_id for every request for debugging.

FAQ

In the dashboard under API/Integrations. Store keys on your backend only.

You should set rate limits to protect the system. Exceeding them returns 429.

Yes. Map the rules structure to your backend (geo/device/time + fallback).

Want to integrate via API?

Generate an API key and start creating links/analytics via the API.

Open dashboard Read Getting started