Kliq
API/Admin API

Admin API

Automate every Kliq link and attribution workflow with the stable v1 API.

The Kliq Admin API is a public, versioned HTTP API for trusted services and agents authorized by a Kliq organization. Every request is scoped to the organization attached to its API key or OAuth token, so an organization identifier is never accepted from the client.

Base URL

https://kliq.sh/api/v1

The complete machine-readable contract is available without authentication:

https://kliq.sh/api/v1/openapi.json

An agent-ready operational guide is also available at /api/v1/agent-skill. The unified tool catalog is available at /api/v1/tools, and the MCP endpoint is https://kliq.sh/api/mcp. Setup: Configure AI Agents. Catalog: Agent Tools.

Authentication

Create a revocable organization API key in Settings → API keys, then send it as a bearer token:

Authorization: Bearer nsk_••••••••

The x-api-key header is accepted for compatibility. Never put a key in a URL, browser bundle, log, prompt, or source-control repository.

MCP clients can also use OAuth 2.1 discovery. Kliq dynamically registers the client, asks an owner or admin to choose an organization, and issues a token with explicit Kliq scopes. The protected-resource document lives at /.well-known/oauth-protected-resource/api/mcp.

MCP and unified tools

Kliq exposes 26 tools across account, members, domains, links, analytics, customers, events, and imports. MCP, GET/POST /api/v1/tools, and pnpm tools all use the same registry and execute the existing Admin API logic. See Configure AI Agents and Agent Tools.

First request

curl https://kliq.sh/api/v1/me \
  -H "Authorization: Bearer $KLIQ_API_KEY"

Use /me during setup to confirm which organization the key controls.

Resources

ResourceOperations
/meConfirm the organization attached to the credential
/membersList members (members:read, not on default keys)
/members/{id}Read one member
/domainsList, register, read, and update short-link domains
/linksList and create canonical parent links
/links/{id}Read, update, or archive any link
/links/{id}/sublinksList and create placement sublinks
/analyticsRead organization totals, daily series, and top links
/links/{id}/analyticsRead parent, sublink, and imported statistics
/customersList attributed customers and filter by link
/customers/{externalId}Read a customer and their event journey
/eventsList events or ingest a trusted server event/conversion
/track/leadBind a click to a customer, by user ID or email alone
/track/saleRecord revenue for a customer that already has a lead
/importsInspect migration batches and row-level results
/toolsList the 26-tool adapter, inspect a schema, execute

Pagination

List endpoints accept limit from 1 to 100 and an opaque cursor. Pass the returned cursor unchanged on the next request:

{
  "data": [],
  "pagination": {
    "cursor": "opaque-cursor-or-null",
    "isDone": false
  }
}

Idempotent writes

Creating a parent, creating a sublink, and ingesting an event or lead require an idempotencyKey. Repeating the same request with the same key returns the existing result. Reusing that key for different data returns 409.

POST /track/sale accepts invoiceId in place of an explicit key, so a redelivered billing webhook cannot double-count revenue. Only the business identity of the event matters — a retry that carries a later timestamp is still the same event.

Use a stable business identifier such as campaign-launch-parent-v1, not a new random value on every retry.

Errors

API errors have a stable shape:

{
  "error": {
    "code": "validation_error",
    "message": "destinationUrl must be a valid HTTP or HTTPS URL"
  }
}
StatusMeaning
401Key missing, invalid, expired, or revoked
404Resource absent or outside the key's organization
409Slug, domain, or idempotency conflict
413JSON request exceeds 64 KB
422Validation failed
429API-key rate limit exceeded
500Unexpected server failure; retry with backoff
503A required Kliq integration is unavailable

Reliability conventions

  • Timestamps are Unix milliseconds.
  • Revenue uses integer minor units and a three-letter currency code.
  • Analytics ranges are inclusive UTC days and cannot exceed 367 days.
  • Cursors are opaque and must not be decoded or modified.
  • DELETE /links/{id} archives the URL; published links are never physically deleted.
  • A sublink inherits its parent's destination and social metadata.
  • Links are active by default; an unverified domain prevents redirects until it is verified.

Agent usage

Connect MCP, install the skill, and follow the operational rules in Configure AI Agents. Agents should fetch OpenAPI and /api/v1/tools at startup, keep credentials in secret storage, reuse idempotency keys on retries, follow every pagination cursor, and back off after 429 or transient 500 responses.

Links API