REST API Overview · Taqlyn Docs

The Taqlyn REST API provides programmatic access to link creation, mobile deferred deep link matching, app registration, edge domain routing, and telemetry ingestion.

Try it: Open the Interactive API Reference from the docs, or use Try API in the dashboard (sandbox only). The console covers server SDK (Ed25519-signed) routes; paste your sandbox private PEM once per tab.

#Base URLs & Environments

All API endpoints require HTTPS and operate across two isolated environments:

Environment	Base URL	Client ID Prefix	Purpose
Sandbox / Test	`https://api.taqlyn.com`	`app_test_*`	Development, CI/CD testing, staging simulator runs.
Production / Live	`https://api.taqlyn.com`	`app_live_*`	Production mobile apps and live customer traffic.

The target environment is determined cryptographically by the clientId used during authentication.

#Authentication Schemes

Taqlyn uses three distinct authentication tiers depending on the caller and sensitivity:

CODE

┌─────────────────────────┬───────────────────────────────┬──────────────────────────────────────────┐
│ Caller                  │ Auth Mechanism                │ Permitted Operations                     │
├─────────────────────────┼───────────────────────────────┼──────────────────────────────────────────┤
│ Backend Servers / SDKs  │ Ed25519 Request Signing       │ Create short links, patch, delete, bind  │
│ Mobile Applications     │ Public Key ID (Unsigned)      │ Resolve, expand, trackOpen, logEvent     │
│ Dashboard Console       │ Bearer Session Cookie / Token │ Org management, billing, credentials     │
└─────────────────────────┴───────────────────────────────┴──────────────────────────────────────────┘

#1. Server Ed25519 Request Signing

Privileged endpoints (POST /v1/short-links, PATCH /v1/short-links/{id}, POST /v1/apps) require three cryptographic headers generated using your private key:

X-Taqlyn-Client-Id: Your app identifier (app_test_* or app_live_*).
X-Taqlyn-Timestamp: Unix epoch in seconds.
X-Taqlyn-Signature: Base64-encoded Ed25519 digital signature of the canonical request.

See Signed Requests for the step-by-step canonical format.

#2. Mobile Public Resolution

Mobile clients call these endpoints with only public credentials:

POST /v1/resolve — deferred Match after install
POST /v1/links/expand — warm short-code → in-app path (Expand API)
POST /v1/events/open / POST /v1/events/sdk — analytics

Credentials:

clientId: Identifies your app.
publicKeyId: Identifies the active credential (pk_test_* or pk_live_*).

The private key is never embedded in mobile client binaries.

#3. Console Session

Dashboard users authenticate via email/password, TOTP, or WebAuthn Passkeys, receiving an HTTP-only session cookie for session endpoints.

#Standard JSON Error Envelope

All error responses return standard HTTP status codes accompanied by a structured JSON payload:

JSON

{
  "error": "links.invalid_destination",
  "message": "destinationWeb must be an absolute HTTPS URL"
}

#Common HTTP Status Codes

Code	Meaning	Typical Scenario
`200 OK`	Success	Retrieved resource or successful deferred match.
`201 Created`	Resource Created	Short link or app successfully created.
`400 Bad Request`	Validation Error	Missing parameters, malformed JSON, or invalid schema.
`401 Unauthorized`	Auth Failure	Invalid Ed25519 signature, expired timestamp, or bad `publicKeyId`.
`403 Forbidden`	Access Denied	Organization plan cap reached or resource belongs to another org.
`404 Not Found`	Resource Missing	Link ID does not exist or has expired.
`429 Too Many Requests`	Rate Limited	Exceeded API rate limits (100 req/sec standard burst).
`500 Server Error`	Internal Failure	Contact support or retry with exponential backoff.

#Content Types & Character Encoding

Always send Content-Type: application/json; charset=utf-8 on requests with JSON bodies.
API responses are returned as application/json; charset=utf-8.