LinkQuick
API/Admin API

Admin API

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

The LinkQuick Admin API is a public, versioned HTTP API for trusted internal services and agents. Every request is scoped to the organization that owns the API key, so an organization identifier is never accepted from the client.

Base URL

https://linkquick.melvynx.dev/api/v1

The complete machine-readable contract is available without authentication:

https://linkquick.melvynx.dev/api/v1/openapi.json

An agent-ready operational guide is also available at /api/v1/agent-skill.

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.

First request

curl https://linkquick.melvynx.dev/api/v1/me \
  -H "Authorization: Bearer $LINKQUICK_API_KEY"

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

Resources

ResourceOperations
/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

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 LinkQuick 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

Agents should fetch the OpenAPI document 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