Cometly APIv1 OpenAPI

API reference

Version 1 · OpenAPI 3.1 · Dashboard

Introduction

The Cometly API lets you create branded short links and QR codes, connect your own domains, watch their health and reputation, and report conversions — everything the dashboard does.

Base URLhttps://api.cometly.site
FormatJSON · UTF-8
TimesISO 8601, UTC
Specopenapi.json

Quick start

  1. In the dashboard, open Settings → API keys and create a key with the links:write scope. Copy it — it’s shown once.
  2. Paste it in the API key box at the top of this page to fill in every example (it stays in this tab; nothing is stored or sent).
  3. Create your first link:
cURL
curl -X POST "https://api.cometly.site/v1/links" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://kesari.shop/diwali", "slug": "diwali"}'

IDs carry a prefix that tells you what they are: lnk_ link, dom_ domain, ws_ workspace, usr_ user, key_ API key, job_ job, cnv_ conversion, clk_ click.

Authentication

Send your key as a bearer token on every /v1 request:

Authorization: Bearer cmt_live_…

Keys belong to a workspace, carry scopes, and can be limited to some domains (allowed_domain_ids). A key can never have more access than the person who created it. Keep keys on your server — the API refuses browser calls from other websites.

Repeatedly sending invalid keys from one network gets that network temporarily blocked (403 ip-blocked).

The dashboard uses cookie sessions instead (see Dashboard sign-in); those requests also need X-CSRF-Token on writes and X-Workspace-Id to pick a workspace.

Scopes & roles

Give each key only the scopes it needs. Team members get scopes from their role.

ScopeAllowsOwner / AdminMemberViewer
links:readRead links, QR codes’ settings, health and safety✓✓✓
links:writeCreate and edit links, builders, QR designs✓✓—
links:deleteDelete and purge links✓✓—
domains:readRead domains, DNS guides, reputation✓✓✓
domains:writeAdd, verify and edit domains✓✓—
domains:deleteDelete or cancel domains✓——
stats:readTraffic quality and analytics✓✓✓
qr:readDownload QR codes✓✓✓
webhooks:writeManage webhooks✓——
keys:writeCreate, list and revoke API keys✓——
account:readWorkspace, plan, usage, team, jobs✓✓✓
conversions:readList conversions✓✓✓
conversions:writeReport conversions✓✓—
integrations:writeConnect Meta CAPI and GA4✓——
team:writeInvite, change and remove members✓——

Errors

Errors use problem details with Content-Type: application/problem+json. Branch on type (a stable code); show detail to people. Validation errors list each bad field.

422application/problem+json
{
  "type": "validation-error",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "slug",
      "message": "Use 1–60 letters, digits, - or _"
    }
  ]
}
400Malformed JSON or headers
401Missing, invalid, revoked or expired key
402Plan limit reached (link-limit-reached, domain-limit-reached)
403Missing scope (insufficient-scope), role, or domain access; suspended workspace
404Not found — or not in your workspace
409Conflict (slug-taken, domain-in-use…)
412If-Match didn’t match the current ETag
422Validation failed, or destination-blocked (phishing/malware)
429Rate limited — wait Retry-After seconds
503A dependency is briefly unavailable; nothing was changed — retry with backoff

Pagination

List endpoints return {"data": [...], "next_cursor": "…"}. Pass cursor=<next_cursor> for the next page; next_cursor is null on the last page. limit is 1–100 (default 50).

Retries & concurrency

Idempotency. Send Idempotency-Key: <unique string> on any POST. For 24 hours a retry with the same key and body returns the original response (with Idempotent-Replayed: true) instead of creating a duplicate. Reusing a key with a different body is 422 idempotency-key-reused; a retry while the first is still running is 409 operation-in-progress.

Safe edits. Links return an ETag. Send it back as If-Match on PATCH and you’ll get 412 instead of overwriting a change someone else just made.

Rate limits

Each key may make 60 / 600 / 3,000 requests per minute on Free / Pro / Business (your number is limits.api_rate_limit in GET /v1/me); a workspace may use 3× that across all keys. Every response carries:

RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 41

When you go over you get 429 with Retry-After (seconds). There is also a per-network limit in front of the API to absorb floods.

Webhooks

Coming soon: the endpoints to register webhook URLs (POST /v1/webhooks) are in the next build phase. Events are already recorded in this format, so you can build your receiver now.

Each delivery is a POST with a JSON event. Deliveries are at-least-once — dedupe on id.

Event
{
  "id": "evt_0f8c2b6e-5d1a-4c4e-9a63-2b7d1f0e9c11",
  "type": "domain.blocklisted",
  "created_at": "2026-11-03T10:05:00.000Z",
  "data": {
    "domain_id": "dom_kd292xv8n8tg",
    "hostname": "go.kesari.shop",
    "status": "listed",
    "listed_on": [
      "meta",
      "spamhaus_dbl"
    ]
  }
}

Verify the X-Cometly-Signature header — an HMAC-SHA256 of <t>.<raw body> with your webhook secret — before trusting the body:

Node.js
import { createHmac, timingSafeEqual } from 'node:crypto';

// header: X-Cometly-Signature: t=1793700000,v1=5f2b…
export function verifyCometly(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  const age = Math.abs(Date.now() / 1000 - Number(parts.t));
  if (!parts.t || !parts.v1 || age > 300) return false; // replayed or stale
  const expected = createHmac('sha256', secret).update(`${parts.t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length &&
    timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

Events

link.createdA link was created
link.updatedA link changed (changed lists the fields)
link.disabledPaused by a user
link.deletedSoft-deleted
link.restoredRestored
link.purgedPermanently deleted
link.expiredReached expires_at or max_clicks
link.flaggedDisabled for a malicious destination or by staff
link.destination_downDestination confirmed down
link.destination_recoveredBack up
link.ab_completedA winner was picked
conversion.createdA conversion was recorded
domain.verifiedDNS verified
domain.tls_issuedHTTPS is live
domain.misconfiguredDNS stopped pointing at us
domain.failedNever verified within 72 h
domain.disabledMisconfigured for 14 days, or over the plan limit
domain.deletion_scheduledDeletion started
domain.restoredRestored
domain.deletedGone
domain.suspendedSuspended by staff
domain.blocklistedNewly listed by Meta, Google, Spamhaus…
domain.reputation_recoveredNo longer listed
job.completedA job finished
job.failedA job failed

Coming soon

These endpoints are reserved and currently answer 501 not-implemented:

GET/v1/links/:id/statsPhase 4
GET/v1/links/:id/clicksPhase 4
POST/v1/links/bulk-deletePhase 3
GET/v1/stats/overviewPhase 4
GET/v1/stats/timeseriesPhase 4
GET/v1/stats/topPhase 4
GET/v1/usagePhase 3
POST/v1/webhooksPhase 3
GET/v1/webhooksPhase 3
POST/v1/exportsPhase 7

Account

Who you are, your plan, limits and usage.

GET/v1/me

Get your workspace, plan and usage

API keyaccount:read
curl "https://api.cometly.site/v1/me" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "workspace": {
    "id": "ws_tg5pvg2u7mwj",
    "name": "Kesari Foods",
    "status": "active",
    "default_domain_id": "dom_kd292xv8n8tg"
  },
  "plan": {
    "id": "pro",
    "name": "Pro"
  },
  "limits": {
    "max_domains": 10,
    "max_links_month": 50000,
    "api_rate_limit": 600
  },
  "usage": {
    "domains": 2,
    "links_this_month": 318
  },
  "credits": {
    "balance": 4820
  },
  "api_key": {
    "id": "key_wnvafcpj2ppr",
    "scopes": [
      "links:read",
      "links:write"
    ],
    "allowed_domains": null
  },
  "member": null
}

Link builders & deep links

Build WhatsApp, UPI, Google Maps, Telegram and app-store links from plain fields, and see which apps open automatically.

POST/v1/builders/:type

Preview a WhatsApp, UPI, Maps, Telegram or app-store link

API keylinks:write

Returns the built URL and a ready link_request to POST to /v1/links. Fields by type — whatsapp: phone, text, country (default IN). upi: pa (VPA), pn (payee), am, tn, tr, mc. maps: mode (search|directions|review), query, place_id. telegram: username, start. app: ios_url, android_url, web_url.

Path parameters

  • typestringrequired
    whatsapp, upi, maps, telegram or app
curl -X POST "https://api.cometly.site/v1/builders/whatsapp" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "098765 43210",
    "text": "Hi! I saw your Diwali offer"
  }'
200application/json
{
  "url": "https://wa.me/919876543210?text=Hi!%20I%20saw%20your%20Diwali%20offer",
  "link_type": "url",
  "warnings": [],
  "summary": "WhatsApp chat with +919876543210",
  "link_request": {
    "builder": {
      "type": "whatsapp",
      "phone": "098765 43210",
      "text": "Hi! I saw your Diwali offer"
    }
  }
}

QR codes

Branded QR codes for any link. Every saved design is rendered and decoded before it’s accepted, and scans are counted separately from clicks (clicks.qr_scans).

GET/v1/qr/settings

Get the workspace QR style

API keyqr:read
curl "https://api.cometly.site/v1/qr/settings" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "style": {
    "fg": "#1E1847",
    "bg": "#FFFFFF",
    "dots": "square",
    "corners": "square",
    "corner_dots": "square",
    "margin": 4,
    "ecl": "M",
    "logo": true,
    "logo_size": 0.22
  },
  "has_logo": true,
  "logo_sha256": "9c1f…"
}
PUT/v1/qr/settings

Set the workspace QR style and logo

API keylinks:write

Logo: a PNG, JPEG or WebP data URI up to 512 KB (SVG refused). It’s re-encoded to ≤ 512 px. logo: null removes it.

Body

  • styleobject
    Same fields as a link design
  • logostring | null
    data:image/png;base64,…
curl -X PUT "https://api.cometly.site/v1/qr/settings" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "style": {
      "fg": "#1E1847",
      "corners": "rounded"
    },
    "logo": "data:image/png;base64,iVBORw0KGgo…"
  }'
200application/json
{
  "style": {
    "fg": "#1E1847",
    "bg": "#FFFFFF",
    "dots": "square",
    "corners": "rounded",
    "corner_dots": "square",
    "margin": 4,
    "ecl": "M",
    "logo": true,
    "logo_size": 0.22
  },
  "has_logo": true,
  "logo_sha256": "9c1f…",
  "warnings": []
}

A/B tests

Split traffic between destinations and pick a winner on conversions (Bayesian chance to win, with a sample-ratio check).

POST/v1/links/:id/ab-test/complete

Finish a test and keep the winner

API keylinks:write

Path parameters

  • idstringrequired
    Link ID

Body

  • winner_idstringrequired
    Variant id, e.g. b
curl -X POST "https://api.cometly.site/v1/links/lnk_594ufv74rqre/ab-test/complete" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "winner_id": "b"
  }'
200application/json
{
  "id": "lnk_594ufv74rqre",
  "short_url": "https://go.kesari.shop/diwali",
  "qr_url": "https://api.cometly.site/v1/links/lnk_594ufv74rqre/qr",
  "domain": "go.kesari.shop",
  "slug": "diwali",
  "destination": "https://kesari.shop/v2",
  "title": "Diwali sale",
  "tags": [
    "instagram"
  ],
  "utm": {
    "source": "instagram",
    "medium": "paid",
    "campaign": "diwali26"
  },
  "preview": null,
  "rules": [
    {
      "if": {
        "device": "ios"
      },
      "url": "https://apps.apple.com/in/app/kesari/id123"
    }
  ],
  "has_password": false,
  "expires_at": null,
  "max_clicks": null,
  "status": "active",
  "disabled_reason": null,
  "metadata": {},
  "type": "url",
  "deep_link": {
    "mode": "off"
  },
  "ab_test": null,
  "conversion_tracking": true,
  "fallback_url": "https://kesari.shop/",
  "health": {
    "state": "unknown"
  },
  "clicks": {
    "total": 0,
    "last_24h": 0,
    "suspicious": 0,
    "filtered": 0,
    "qr_scans": 0
  },
  "safety": {
    "verdict": "clean",
    "review": null,
    "reasons": [],
    "checked_at": "2026-11-03T10:02:10.000Z"
  },
  "conversions": {
    "total": 0,
    "value": 0
  },
  "etag": "vsd7hv73x8s672m3",
  "created_at": "2026-11-03T10:23:30.000Z",
  "updated_at": "2026-11-03T10:23:30.000Z"
}

Link health & traffic quality

Broken-destination monitoring and the bot/fraud breakdown of a link’s clicks.

POST/v1/links/:id/health/check

Check the destination now

API keylinks:write

Path parameters

  • idstringrequired
    Link ID
curl -X POST "https://api.cometly.site/v1/links/lnk_594ufv74rqre/health/check" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "link_id": "lnk_594ufv74rqre",
  "health": {
    "state": "up",
    "destination_down": false
  }
}

Link safety

Every destination and redirect hop is checked against phishing/malware feeds, Google Safe Browsing and heuristics. Malicious destinations are refused (422 destination-blocked) or disabled.

POST/v1/links/:id/safety/check

Re-check now (follows redirects)

API keylinks:write

Path parameters

  • idstringrequired
    Link ID
curl -X POST "https://api.cometly.site/v1/links/lnk_594ufv74rqre/safety/check" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "verdict": "malicious",
  "review": "blocked",
  "reasons": [
    "Listed by openphish as phishing (host phish.example)"
  ],
  "checked_at": "2026-11-03T10:40:00.000Z",
  "chain": [
    "https://bit.ly/3x",
    "https://phish.example/login"
  ],
  "status": "disabled"
}

Conversions & integrations

Report leads and sales against a click (cmt_id) and forward them to Meta Conversions API and GA4.

POST/v1/conversions

Report a lead or sale

API keyconversions:write

Send the cmt_id your landing page received as click_id (or set external_id to attribute repeat purchases to the customer’s first click). event_id makes it idempotent (a repeat returns the first conversion with 200) and is passed to Meta for deduplication.

Body

  • click_idstring
    clk_… from the cmt_id URL parameter
  • eventstringrequired
    lead, sale or a custom name
  • valuenumber
    Order value
  • currencystring
    ISO 4217, e.g. INR
  • event_idstring
    Your order/lead id (dedupe)
  • external_idstring
    Your customer id
  • occurred_atstring (date-time)
    Default now
  • user_dataobject
    {email, phone, client_ip_address, client_user_agent, fbp, ga_client_id} — hashed before forwarding
  • metadataobject
    ≤ 4 KB

Errors

404click-not-foundUnknown click_id (clicks are kept 13 months)
curl -X POST "https://api.cometly.site/v1/conversions" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "clk_7m2xq9kd4hfa8pne",
    "event": "sale",
    "value": 1499,
    "currency": "INR",
    "event_id": "order-1182",
    "external_id": "cust_42",
    "user_data": {
      "email": "asha@example.com"
    }
  }'
201application/json
{
  "id": "cnv_8hq2m5x7tz3c",
  "link_id": "lnk_594ufv74rqre",
  "click_id": "clk_7m2xq9kd4hfa8pne",
  "variant_id": null,
  "event_type": "sale",
  "event_name": "sale",
  "value": 1499,
  "currency": "INR",
  "event_id": "order-1182",
  "occurred_at": "2026-11-03T10:45:00.000Z",
  "forwarding": {
    "meta_capi": "queued",
    "ga4": "queued"
  }
}
GET/v1/conversions

List conversions

API keyconversions:read

Query parameters

  • link_idstring
    Filter by link
  • eventstring
    Filter by event name
  • limitinteger
    1–200, default 50, newest first
curl "https://api.cometly.site/v1/conversions?link_id=lnk_594ufv74rqre&event=sale" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "data": [
    {
      "id": "cnv_8hq2m5x7tz3c",
      "event_name": "sale",
      "value": 1499,
      "currency": "INR",
      "link_id": "lnk_594ufv74rqre",
      "occurred_at": "2026-11-03T10:45:00.000Z"
    }
  ]
}
GET/v1/integrations

List integrations

API keyaccount:read
curl "https://api.cometly.site/v1/integrations" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "data": [
    {
      "kind": "ga4",
      "enabled": true,
      "config": {
        "measurement_id": "G-ABC1234"
      },
      "last_error": null,
      "updated_at": "2026-11-03T10:50:00.000Z"
    }
  ]
}
PUT/v1/integrations/:kind

Connect Meta CAPI or GA4

API keyintegrations:write

meta_capi: pixel_id, access_token, api_version, test_event_code, enabled. ga4: measurement_id, api_secret, enabled. Secrets are encrypted and never returned.

Path parameters

  • kindstringrequired
    meta_capi or ga4
curl -X PUT "https://api.cometly.site/v1/integrations/ga4" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "measurement_id": "G-ABC1234",
    "api_secret": "xxxxxxxxxxxx"
  }'
200application/json
{
  "kind": "ga4",
  "enabled": true,
  "config": {
    "measurement_id": "G-ABC1234"
  }
}
DELETE/v1/integrations/:kind

Disconnect an integration

API keyintegrations:write

Path parameters

  • kindstringrequired
    meta_capi or ga4
curl -X DELETE "https://api.cometly.site/v1/integrations/ga4" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "deleted": true
}

Domains

Bring your own (sub)domain. Add it, create the DNS records shown, then verify. HTTPS is issued automatically.

POST/v1/domains

Add a domain

API keydomains:write

Returns the DNS records to create: a TXT record proving ownership and a CNAME (subdomain) or A/AAAA (root domain) for routing.

Body

  • hostnamestringrequired
    e.g. go.yourbrand.com (Unicode allowed)
  • homepage_urlstring
    Where the bare domain redirects
  • not_found_urlstring
    Where unknown slugs redirect

Errors

409domain-in-useConnected to another workspace
422invalid-hostnameNot under a public suffix, reserved or a look-alike of a brand
402domain-limit-reachedPlan limit
curl -X POST "https://api.cometly.site/v1/domains" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hostname": "go.kesari.shop"
  }'
201application/json
{
  "id": "dom_kd292xv8n8tg",
  "hostname": "go.kesari.shop",
  "hostname_unicode": "go.kesari.shop",
  "type": "subdomain",
  "status": "pending_dns",
  "is_default": false,
  "dns_records": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "name": "_cometly-verify.go.kesari.shop",
      "value": "cometly-verify=4b13de118bc0f44036cd",
      "ttl": 300,
      "required": true
    },
    {
      "purpose": "routing",
      "type": "CNAME",
      "name": "go.kesari.shop",
      "value": "edge.cometly.site",
      "ttl": 300,
      "required": true
    }
  ],
  "checks": {
    "ownership": "pending",
    "routing": "pending",
    "https": "pending"
  },
  "notes": [
    "If you use Cloudflare, set the routing record to 'DNS only' (grey cloud).",
    "If your domain has CAA records, allow letsencrypt.org."
  ],
  "homepage_url": null,
  "not_found_url": null,
  "failure_reason": null,
  "disabled_reason": null,
  "verify_url": "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/verify",
  "last_checked_at": null,
  "next_check_at": "2026-11-03T10:00:00.000Z",
  "verified_at": null,
  "tls_issued_at": null,
  "misconfigured_since": null,
  "created_at": "2026-11-03T10:00:00.000Z"
}
GET/v1/domains

List domains

API keydomains:read

Query parameters

  • statusstring
    pending_dns, verifying, active, misconfigured, disabled, pending_deletion…
  • limitinteger
    1–100, default 50
  • cursorstring
    Opaque cursor from the previous page’s next_cursor
curl "https://api.cometly.site/v1/domains" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "data": [
    {
      "id": "dom_kd292xv8n8tg",
      "hostname": "go.kesari.shop",
      "hostname_unicode": "go.kesari.shop",
      "type": "subdomain",
      "status": "active",
      "is_default": false,
      "dns_records": [
        {
          "purpose": "ownership",
          "type": "TXT",
          "name": "_cometly-verify.go.kesari.shop",
          "value": "cometly-verify=4b13de118bc0f44036cd",
          "ttl": 300,
          "required": true
        },
        {
          "purpose": "routing",
          "type": "CNAME",
          "name": "go.kesari.shop",
          "value": "edge.cometly.site",
          "ttl": 300,
          "required": true
        }
      ],
      "checks": {
        "ownership": "pending",
        "routing": "pending",
        "https": "pending"
      },
      "notes": [
        "If you use Cloudflare, set the routing record to 'DNS only' (grey cloud).",
        "If your domain has CAA records, allow letsencrypt.org."
      ],
      "homepage_url": null,
      "not_found_url": null,
      "failure_reason": null,
      "disabled_reason": null,
      "verify_url": "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/verify",
      "last_checked_at": null,
      "next_check_at": "2026-11-03T10:00:00.000Z",
      "verified_at": null,
      "tls_issued_at": null,
      "misconfigured_since": null,
      "created_at": "2026-11-03T10:00:00.000Z"
    }
  ],
  "next_cursor": null
}
GET/v1/domains/:id

Get a domain

API keydomains:read

Path parameters

  • idstringrequired
    Domain ID
curl "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "id": "dom_kd292xv8n8tg",
  "hostname": "go.kesari.shop",
  "hostname_unicode": "go.kesari.shop",
  "type": "subdomain",
  "status": "pending_dns",
  "is_default": false,
  "dns_records": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "name": "_cometly-verify.go.kesari.shop",
      "value": "cometly-verify=4b13de118bc0f44036cd",
      "ttl": 300,
      "required": true
    },
    {
      "purpose": "routing",
      "type": "CNAME",
      "name": "go.kesari.shop",
      "value": "edge.cometly.site",
      "ttl": 300,
      "required": true
    }
  ],
  "checks": {
    "ownership": "pending",
    "routing": "pending",
    "https": "pending"
  },
  "notes": [
    "If you use Cloudflare, set the routing record to 'DNS only' (grey cloud).",
    "If your domain has CAA records, allow letsencrypt.org."
  ],
  "homepage_url": null,
  "not_found_url": null,
  "failure_reason": null,
  "disabled_reason": null,
  "verify_url": "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/verify",
  "last_checked_at": null,
  "next_check_at": "2026-11-03T10:00:00.000Z",
  "verified_at": null,
  "tls_issued_at": null,
  "misconfigured_since": null,
  "created_at": "2026-11-03T10:00:00.000Z"
}
PATCH/v1/domains/:id

Update a domain

API keydomains:write

Path parameters

  • idstringrequired
    Domain ID

Body

  • homepage_urlstring | null
    Bare-domain redirect
  • not_found_urlstring | null
    Unknown-slug redirect
  • is_defaultboolean
    Make it the workspace default
curl -X PATCH "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_default": true,
    "not_found_url": "https://kesari.shop/"
  }'
200application/json
{
  "id": "dom_kd292xv8n8tg",
  "hostname": "go.kesari.shop",
  "hostname_unicode": "go.kesari.shop",
  "type": "subdomain",
  "status": "active",
  "is_default": true,
  "dns_records": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "name": "_cometly-verify.go.kesari.shop",
      "value": "cometly-verify=4b13de118bc0f44036cd",
      "ttl": 300,
      "required": true
    },
    {
      "purpose": "routing",
      "type": "CNAME",
      "name": "go.kesari.shop",
      "value": "edge.cometly.site",
      "ttl": 300,
      "required": true
    }
  ],
  "checks": {
    "ownership": "pending",
    "routing": "pending",
    "https": "pending"
  },
  "notes": [
    "If you use Cloudflare, set the routing record to 'DNS only' (grey cloud).",
    "If your domain has CAA records, allow letsencrypt.org."
  ],
  "homepage_url": null,
  "not_found_url": "https://kesari.shop/",
  "failure_reason": null,
  "disabled_reason": null,
  "verify_url": "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/verify",
  "last_checked_at": null,
  "next_check_at": "2026-11-03T10:00:00.000Z",
  "verified_at": null,
  "tls_issued_at": null,
  "misconfigured_since": null,
  "created_at": "2026-11-03T10:00:00.000Z"
}
POST/v1/domains/:id/verify

Check DNS now

API keydomains:write

DNS is checked through two resolvers; a domain goes verifying on the first agreeing check and active once DNS still agrees ≥ 2 minutes later and HTTPS is live. Checks also run automatically.

Path parameters

  • idstringrequired
    Domain ID
curl -X POST "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/verify" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "id": "dom_kd292xv8n8tg",
  "hostname": "go.kesari.shop",
  "hostname_unicode": "go.kesari.shop",
  "type": "subdomain",
  "status": "active",
  "is_default": false,
  "dns_records": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "name": "_cometly-verify.go.kesari.shop",
      "value": "cometly-verify=4b13de118bc0f44036cd",
      "ttl": 300,
      "required": true
    },
    {
      "purpose": "routing",
      "type": "CNAME",
      "name": "go.kesari.shop",
      "value": "edge.cometly.site",
      "ttl": 300,
      "required": true
    }
  ],
  "checks": {
    "ownership": "ok",
    "routing": "ok",
    "https": "ok",
    "caa": "ok"
  },
  "notes": [
    "If you use Cloudflare, set the routing record to 'DNS only' (grey cloud).",
    "If your domain has CAA records, allow letsencrypt.org."
  ],
  "homepage_url": null,
  "not_found_url": null,
  "failure_reason": null,
  "disabled_reason": null,
  "verify_url": "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/verify",
  "last_checked_at": null,
  "next_check_at": "2026-11-03T10:00:00.000Z",
  "verified_at": null,
  "tls_issued_at": null,
  "misconfigured_since": null,
  "created_at": "2026-11-03T10:00:00.000Z"
}
GET/v1/domains/:id/dns-instructions

Step-by-step DNS guide

API keydomains:read

Path parameters

  • idstringrequired
    Domain ID

Query parameters

  • providerstring
    cloudflare, godaddy, namecheap, hostinger, google, route53
curl "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/dns-instructions?provider=cloudflare" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "domain_id": "dom_kd292xv8n8tg",
  "hostname": "go.kesari.shop",
  "provider": "cloudflare",
  "provider_name": "Cloudflare",
  "supported_providers": [
    "cloudflare",
    "godaddy",
    "namecheap",
    "hostinger",
    "google",
    "route53"
  ],
  "steps": [
    "Open dash.cloudflare.com, pick the domain, then go to DNS → Records."
  ],
  "records": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "name": "_cometly-verify.go.kesari.shop",
      "value": "cometly-verify=4b13de118bc0f44036cd",
      "ttl": 300,
      "required": true
    },
    {
      "purpose": "routing",
      "type": "CNAME",
      "name": "go.kesari.shop",
      "value": "edge.cometly.site",
      "ttl": 300,
      "required": true
    }
  ],
  "notes": [
    "If you use Cloudflare, set the routing record to 'DNS only' (grey cloud).",
    "If your domain has CAA records, allow letsencrypt.org."
  ]
}
GET/v1/domains/:id/health

Last DNS/HTTPS check

API keydomains:read

Path parameters

  • idstringrequired
    Domain ID
curl "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/health" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "domain_id": "dom_kd292xv8n8tg",
  "hostname": "go.kesari.shop",
  "status": "active",
  "last_check": {
    "checked_at": "2026-11-03T10:02:10.000Z",
    "ownership_ok": true,
    "routing_ok": true,
    "https_ok": true,
    "caa_ok": true,
    "proxied": false
  },
  "certificate": {
    "issued_at": "2026-11-03T10:02:10.000Z"
  },
  "reputation": {
    "status": "ok",
    "checked_at": "2026-11-03T10:05:00.000Z",
    "details": "/v1/domains/dom_kd292xv8n8tg/reputation"
  }
}
GET/v1/domains/:id/deletion-preview

What deleting would affect

API keydomains:read

Path parameters

  • idstringrequired
    Domain ID
curl "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/deletion-preview" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "domain_id": "dom_kd292xv8n8tg",
  "hostname": "go.kesari.shop",
  "status": "active",
  "link_count": 128,
  "clicks_last_30_days": 18432,
  "is_default": true,
  "api_keys_limited_to_domain": [],
  "on_links_options": [
    "disable",
    "move",
    "delete"
  ],
  "restore_window_days": 7
}
DELETE/v1/domains/:id

Delete a domain

API keydomains:delete

Choose what happens to its links. Restorable for 7 days. Domains with links need X-Confirm-Hostname. Returns a job to poll.

Path parameters

  • idstringrequired
    Domain ID

Query parameters

  • on_linksstringrequired
    disable, move or delete
  • move_tostring
    Target domain hostname for move
  • on_conflictstring
    fail (default) or suffix (adds -2, -3)
  • purgeboolean
    Skip the 7-day restore window

Headers

  • X-Confirm-Hostnamestring
    Must equal the hostname when links exist
curl -X DELETE "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg?on_links=move&move_to=go2.kesari.shop" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "X-Confirm-Hostname: go.kesari.shop"
202application/json
{
  "id": "dom_kd292xv8n8tg",
  "status": "pending_deletion",
  "job": {
    "id": "job_q8m2x7",
    "status": "queued",
    "url": "/v1/jobs/job_q8m2x7"
  },
  "purge_at": "2026-11-10T10:00:00.000Z"
}
POST/v1/domains/:id/restore

Restore a deleted domain

API keydomains:write

Path parameters

  • idstringrequired
    Domain ID
curl -X POST "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/restore" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "id": "dom_kd292xv8n8tg",
  "hostname": "go.kesari.shop",
  "hostname_unicode": "go.kesari.shop",
  "type": "subdomain",
  "status": "active",
  "is_default": false,
  "dns_records": [
    {
      "purpose": "ownership",
      "type": "TXT",
      "name": "_cometly-verify.go.kesari.shop",
      "value": "cometly-verify=4b13de118bc0f44036cd",
      "ttl": 300,
      "required": true
    },
    {
      "purpose": "routing",
      "type": "CNAME",
      "name": "go.kesari.shop",
      "value": "edge.cometly.site",
      "ttl": 300,
      "required": true
    }
  ],
  "checks": {
    "ownership": "pending",
    "routing": "pending",
    "https": "pending"
  },
  "notes": [
    "If you use Cloudflare, set the routing record to 'DNS only' (grey cloud).",
    "If your domain has CAA records, allow letsencrypt.org."
  ],
  "homepage_url": null,
  "not_found_url": null,
  "failure_reason": null,
  "disabled_reason": null,
  "verify_url": "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/verify",
  "last_checked_at": null,
  "next_check_at": "2026-11-03T10:00:00.000Z",
  "verified_at": null,
  "tls_issued_at": null,
  "misconfigured_since": null,
  "created_at": "2026-11-03T10:00:00.000Z"
}
POST/v1/domains/:id/cancel

Cancel a domain that never verified

API keydomains:delete

Path parameters

  • idstringrequired
    Domain ID
curl -X POST "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/cancel" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "id": "dom_kd292xv8n8tg",
  "status": "deleted"
}

Domain reputation

Is your short domain blocked on Facebook/Instagram, by Chrome/Gmail, on email blocklists or by security vendors? Checked daily and on demand.

GET/v1/domains/:id/reputation

Reputation and blocklist status

API keydomains:read

Checks: meta (Facebook, Messenger, Instagram), safe_browsing (Chrome/Safari/Gmail), spamhaus_dbl, surbl, uribl, virustotal, urlhaus, local_feeds, own_abuse, domain_age, tls. Status per check: ok, warning, listed, error (couldn’t check), skipped (not configured). Platforms without an API are listed under manual_checks.

Path parameters

  • idstringrequired
    Domain ID
curl "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/reputation" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "domain": "go.kesari.shop",
  "status": "listed",
  "checked_at": "2026-11-03T10:05:00.000Z",
  "results": [
    {
      "id": "meta",
      "name": "Meta link safety",
      "affects": "Facebook, Messenger, Instagram",
      "status": "listed",
      "detail": "Meta blocks this domain: The action attempted has been deemed abusive or is otherwise disallowed"
    },
    {
      "id": "spamhaus_dbl",
      "name": "Spamhaus DBL",
      "affects": "Email filters (Gmail, Outlook, ISPs), firewalls",
      "status": "listed",
      "detail": "Listed: abused legit redirector / URL shortener"
    },
    {
      "id": "tls",
      "name": "HTTPS certificate",
      "affects": "Every browser and in-app browser",
      "status": "ok",
      "detail": "Valid for 61 more days (Let’s Encrypt)"
    }
  ],
  "manual_checks": [
    {
      "platform": "LinkedIn",
      "url": "https://www.linkedin.com/post-inspector/inspect/https%3A%2F%2Fgo.kesari.shop%2F"
    },
    {
      "platform": "X, WhatsApp, Telegram, TikTok",
      "url": null,
      "note": "No public check exists"
    }
  ],
  "history": [
    {
      "status": "listed",
      "at": "2026-11-03T10:05:00.000Z"
    },
    {
      "status": "ok",
      "at": "2026-11-02T10:05:00.000Z"
    }
  ]
}
POST/v1/domains/:id/reputation/check

Re-check reputation now

API keydomains:write

Once per 10 minutes per domain. Fires domain.blocklisted / domain.reputation_recovered webhooks on change.

Path parameters

  • idstringrequired
    Domain ID

Errors

429checked-recentlyChecked in the last 10 minutes
curl -X POST "https://api.cometly.site/v1/domains/dom_kd292xv8n8tg/reputation/check" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "domain": "go.kesari.shop",
  "status": "ok",
  "checked_at": "2026-11-03T10:06:00.000Z",
  "results": []
}

Team

Invite people to your workspace with a role: owner, admin, member or viewer.

GET/v1/team

Members and pending invites

API keyaccount:read
curl "https://api.cometly.site/v1/team" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "members": [
    {
      "id": "usr_5fxw9tcypgsq",
      "email": "ananya@kesari.shop",
      "name": "Ananya Kapoor",
      "role": "owner",
      "status": "active",
      "last_login_at": "2026-11-03T09:00:00.000Z",
      "mfa_enabled": true
    }
  ],
  "invites": [
    {
      "id": "a1b2c3d4e5f6a7b8",
      "email": "ravi@kesari.shop",
      "role": "member",
      "created_at": "2026-11-03T10:00:00.000Z",
      "expires_at": "2026-11-10T10:00:00.000Z"
    }
  ]
}
POST/v1/team/invites

Invite someone

API keyteam:write

They get an email link valid for 7 days. Only the owner can invite admins. Seats: Free 2, Pro 10, Business 100.

Body

  • emailstringrequired
    Their email
  • rolestring
    admin, member (default) or viewer

Errors

409already-memberAlready in the workspace
402plan-limitNo seats left
curl -X POST "https://api.cometly.site/v1/team/invites" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ravi@kesari.shop",
    "role": "member"
  }'
201application/json
{
  "email": "ravi@kesari.shop",
  "role": "member",
  "expires_in_days": 7
}
DELETE/v1/team/invites/:id

Cancel an invite

API keyteam:write

Path parameters

  • idstringrequired
    Invite ID
curl -X DELETE "https://api.cometly.site/v1/team/invites/a1b2c3d4e5f6a7b8" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "cancelled": true
}
PATCH/v1/team/members/:id

Change a member’s role

API keyteam:write

Path parameters

  • idstringrequired
    User ID

Body

  • rolestringrequired
    admin, member or viewer
curl -X PATCH "https://api.cometly.site/v1/team/members/usr_5fxw9tcypgsq" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "viewer"
  }'
200application/json
{
  "user_id": "usr_5fxw9tcypgsq",
  "role": "viewer"
}
DELETE/v1/team/members/:id

Remove a member (or leave)

API keyteam:write

Removing yourself only needs account:read.

Path parameters

  • idstringrequired
    User ID
curl -X DELETE "https://api.cometly.site/v1/team/members/usr_5fxw9tcypgsq" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "removed": true
}

API keys & jobs

Create scoped keys (optionally limited to some domains) and poll long-running jobs.

GET/v1/api-keys

List API keys

API keykeys:write
curl "https://api.cometly.site/v1/api-keys" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "data": [
    {
      "id": "key_ywd3cyggdwe3",
      "name": "Zapier",
      "prefix": "cmt_live_q1a7Tv",
      "scopes": [
        "links:read",
        "links:write"
      ],
      "allowed_domain_ids": null,
      "last_used_at": "2026-11-03T10:00:00.000Z",
      "expires_at": null,
      "created_at": "2026-10-01T10:00:00.000Z",
      "created_by": "ananya@kesari.shop"
    }
  ]
}
POST/v1/api-keys

Create an API key

API keykeys:write

The secret is returned once. A key can’t be given scopes or domains its creator doesn’t have.

Body

  • namestringrequired
    1–80 chars
  • scopesstring[]required
    See Scopes
  • allowed_domain_idsstring[] | null
    Limit the key to these domains
  • expires_in_daysinteger
    1–3650

Errors

403scope-escalationMore scopes than you have
curl -X POST "https://api.cometly.site/v1/api-keys" \
  -H "Authorization: Bearer $COMETLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zapier",
    "scopes": [
      "links:read",
      "links:write"
    ],
    "expires_in_days": 365
  }'
201application/json
{
  "id": "key_ywd3cyggdwe3",
  "name": "Zapier",
  "prefix": "cmt_live_q1a7Tv",
  "scopes": [
    "links:read",
    "links:write"
  ],
  "secret": "cmt_live_q1a7Tv0ZBQURv2Z7LWr3oxl9GDkX6t3sgHgIK8Yz",
  "note": "Copy this key now — it won’t be shown again."
}
DELETE/v1/api-keys/:id

Revoke an API key

API keykeys:write

Path parameters

  • idstringrequired
    API key ID
curl -X DELETE "https://api.cometly.site/v1/api-keys/key_ywd3cyggdwe3" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "revoked": true
}
GET/v1/jobs/:id

Poll a job

API keyaccount:read

Path parameters

  • idstringrequired
    Job ID
curl "https://api.cometly.site/v1/jobs/job_q8m2x7" \
  -H "Authorization: Bearer $COMETLY_API_KEY"
200application/json
{
  "id": "job_q8m2x7",
  "type": "domain_deletion",
  "status": "completed",
  "progress": 128,
  "total": 128,
  "result": {
    "links_disabled": 128
  },
  "created_at": "2026-11-03T10:00:00.000Z",
  "finished_at": "2026-11-03T10:00:04.000Z"
}

Dashboard sign-in

Cookie sessions used by the dashboard (app.cometly.site). Writes need the X-CSRF-Token from /auth/me. Integrations should use API keys instead.

GET/auth/config

Sign-up mode and password rules

No auth
curl "https://api.cometly.site/auth/config"
200application/json
{
  "signup_mode": "invite",
  "password_min_length": 10
}
POST/auth/signup

Sign up (when open)

No auth

Same answer whether or not the email exists. Sends a verification email.

Body

  • emailstringrequired
  • passwordstringrequired
    ≥ 10 chars, not a common password
  • namestring
  • workspace_namestring

Errors

403signup-invite-onlySign-up is invite-only
curl -X POST "https://api.cometly.site/auth/signup" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "asha@example.com",
    "password": "monsoon chai on the terrace",
    "name": "Asha",
    "workspace_name": "Asha Foods"
  }'
202application/json
{
  "status": "check-your-email"
}
POST/auth/verify-email

Confirm an email address

No auth

Body

  • tokenstringrequired
    From the email link
curl -X POST "https://api.cometly.site/auth/verify-email" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "TOKEN_FROM_EMAIL"
  }'
200application/json
{
  "status": "verified"
}
POST/auth/verify-email/resend

Resend the verification email

No auth

Body

  • emailstringrequired
curl -X POST "https://api.cometly.site/auth/verify-email/resend" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "asha@example.com"
  }'
202application/json
{
  "status": "check-your-email"
}
POST/auth/login

Sign in

No auth

Sets the __Host-cmt_session cookie. If 2FA is on, returns {mfa_required: true, mfa_token} instead — finish with /auth/login/mfa. 5 wrong passwords pause the account for 1–60 minutes.

Body

  • emailstringrequired
  • passwordstringrequired

Errors

401invalid-credentialsWrong email or password
429too-many-attemptsTemporarily locked
403email-not-verifiedConfirm your email first
curl -X POST "https://api.cometly.site/auth/login" \
  -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ananya@kesari.shop",
    "password": "••••••••••"
  }'
200application/json
{
  "mfa_required": true,
  "mfa_token": "pY3…"
}
POST/auth/login/mfa

Finish sign-in with a 2FA code

No auth

Body

  • mfa_tokenstringrequired
    From /auth/login (valid 5 min)
  • codestring
    6-digit TOTP
  • recovery_codestring
    Instead of code
curl -X POST "https://api.cometly.site/auth/login/mfa" \
  -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "mfa_token": "pY3…",
    "code": "482913"
  }'
200application/json
{
  "user": {
    "id": "usr_5fxw9tcypgsq",
    "email": "ananya@kesari.shop",
    "platform_role": "user",
    "mfa_enabled": true
  },
  "workspaces": [
    {
      "id": "ws_tg5pvg2u7mwj",
      "name": "Kesari Foods",
      "role": "owner"
    }
  ],
  "csrf_token": "Xq1…"
}
POST/auth/logout

Sign out

Dashboard session
curl -X POST "https://api.cometly.site/auth/logout" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
204No content
(empty body)
POST/auth/logout-all

Sign out everywhere

Dashboard session
curl -X POST "https://api.cometly.site/auth/logout-all" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "signed_out_sessions": 3
}
GET/auth/me

Current user, workspaces and CSRF token

Dashboard session
curl "https://api.cometly.site/auth/me" \
  -b cookies.txt -c cookies.txt
200application/json
{
  "user": {
    "id": "usr_5fxw9tcypgsq",
    "email": "ananya@kesari.shop",
    "name": "Ananya Kapoor",
    "platform_role": "user",
    "mfa_enabled": true,
    "email_verified": true
  },
  "workspaces": [
    {
      "id": "ws_tg5pvg2u7mwj",
      "name": "Kesari Foods",
      "status": "active",
      "plan_id": "pro",
      "role": "owner"
    }
  ],
  "session": {
    "id": "ses_nx5tk9z6n7cm",
    "expires_at": "2026-12-03T10:00:00.000Z",
    "read_only": false,
    "impersonated_by": null
  },
  "csrf_token": "Xq1…",
  "mfa_setup_required": false
}
POST/auth/password/forgot

Email a reset link

No auth

Body

  • emailstringrequired
curl -X POST "https://api.cometly.site/auth/password/forgot" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ananya@kesari.shop"
  }'
202application/json
{
  "status": "check-your-email"
}
POST/auth/password/reset

Set a new password from the link

No auth

Signs out every session.

Body

  • tokenstringrequired
    Valid 30 min, single use
  • passwordstringrequired
curl -X POST "https://api.cometly.site/auth/password/reset" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "TOKEN_FROM_EMAIL",
    "password": "a brand new passphrase"
  }'
200application/json
{
  "status": "password-updated"
}
POST/auth/password/change

Change password

Dashboard session

Body

  • current_passwordstringrequired
  • new_passwordstringrequired
curl -X POST "https://api.cometly.site/auth/password/change" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "current_password": "••••",
    "new_password": "a brand new passphrase"
  }'
200application/json
{
  "status": "password-updated",
  "other_sessions_signed_out": 2
}
POST/auth/mfa/setup

Start 2FA setup

Dashboard session
curl -X POST "https://api.cometly.site/auth/mfa/setup" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "secret": "JBSWY3DPEHPK3PXP…",
  "otpauth_url": "otpauth://totp/Cometly:ananya%40kesari.shop?secret=…&issuer=Cometly"
}
POST/auth/mfa/enable

Confirm a code and turn 2FA on

Dashboard session

Body

  • codestringrequired
    6 digits
curl -X POST "https://api.cometly.site/auth/mfa/enable" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "482913"
  }'
200application/json
{
  "enabled": true,
  "recovery_codes": [
    "k7q2-m9xd-4hfa",
    "…"
  ]
}
POST/auth/mfa/disable

Turn 2FA off

Dashboard session

Not allowed for platform staff.

Body

  • passwordstringrequired
  • codestringrequired
curl -X POST "https://api.cometly.site/auth/mfa/disable" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "password": "••••",
    "code": "482913"
  }'
200application/json
{
  "enabled": false
}
POST/auth/mfa/recovery-codes

Make new recovery codes

Dashboard session

Body

  • codestringrequired
    Current TOTP code
curl -X POST "https://api.cometly.site/auth/mfa/recovery-codes" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "482913"
  }'
200application/json
{
  "recovery_codes": [
    "p3vn-8tqe-2wrk",
    "…"
  ]
}
GET/auth/invite

Look at an invite

No auth

Query parameters

  • tokenstringrequired
    From the invite email
curl "https://api.cometly.site/auth/invite?token=INVITE_TOKEN"
200application/json
{
  "email": "ravi@kesari.shop",
  "workspace": "Kesari Foods",
  "role": "member",
  "invited_by": "Ananya Kapoor",
  "needs_password": true,
  "name": ""
}
POST/auth/invite/accept

Accept an invite

No auth

Body

  • tokenstringrequired
  • namestring
  • passwordstring
    Required for new accounts
curl -X POST "https://api.cometly.site/auth/invite/accept" \
  -c cookies.txt \
  -H "Content-Type: application/json" \
  -d '{
    "token": "INVITE_TOKEN",
    "name": "Ravi",
    "password": "teammate passphrase 9"
  }'
200application/json
{
  "user": {
    "id": "usr_r4v1…",
    "email": "ravi@kesari.shop"
  },
  "workspaces": [
    {
      "name": "Kesari Foods",
      "role": "member"
    }
  ],
  "csrf_token": "…"
}
GET/auth/sessions

Signed-in devices

Dashboard session
curl "https://api.cometly.site/auth/sessions" \
  -b cookies.txt -c cookies.txt
200application/json
{
  "data": [
    {
      "id": "ses_nx5tk9z6n7cm",
      "ip": "103.21.58.4",
      "user_agent": "Mozilla/5.0 (Macintosh…)",
      "created_at": "2026-11-01T09:00:00.000Z",
      "last_seen_at": "2026-11-03T10:00:00.000Z",
      "expires_at": "2026-12-01T09:00:00.000Z",
      "impersonation": false,
      "current": true
    }
  ]
}
DELETE/auth/sessions/:id

Sign out one device

Dashboard session

Path parameters

  • idstringrequired
    Session ID
curl -X DELETE "https://api.cometly.site/auth/sessions/ses_nx5tk9z6n7cm" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "revoked": true
}
POST/auth/impersonation/stop

End a support “view as” session

Dashboard session
curl -X POST "https://api.cometly.site/auth/impersonation/stop" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "status": "stopped"
}

Master panel (platform staff)

Platform-owner endpoints. Require a staff account with 2FA proven in this session; others get 404.

GET/admin/overview

Platform overview

Staff session + 2FA
curl "https://api.cometly.site/admin/overview" \
  -b cookies.txt -c cookies.txt
200application/json
{
  "users": {
    "active": 812,
    "invited": 14,
    "suspended": 3,
    "staff": 3,
    "with_mfa": 402,
    "new_30d": 61
  },
  "workspaces": {
    "total": 790,
    "suspended": 2,
    "free": 512,
    "pro": 241,
    "business": 37
  },
  "clicks_24h": {
    "valid": 1204331,
    "filtered": 88102
  },
  "security_24h": {
    "failed_logins": 41,
    "lockouts": 2,
    "auto_bans": 3,
    "csrf_rejected": 1,
    "critical": 0
  },
  "traffic": {
    "minutes": [
      "…"
    ],
    "series": {
      "req_api": [],
      "req_gw": [],
      "rate_limited": [],
      "blocked": []
    }
  }
}
GET/admin/users

List admins & accounts

Staff session + 2FA

Query parameters

  • qstring
    Email, name or id
  • statusstring
    invited|active|suspended|deleted
  • rolestring
    user|support|admin
  • limitinteger
    ≤ 200
  • offsetinteger
curl "https://api.cometly.site/admin/users" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
POST/admin/users/invite

Invite a customer admin (optionally with a workspace)

Staff session + 2FA

Body

  • emailstringrequired
  • namestring
  • workspace_namestring
    Creates their workspace with them as owner
  • plan_idstring
    free|pro|business
  • platform_rolestring
    user (default), support, admin — staff need an admin
curl -X POST "https://api.cometly.site/admin/users/invite" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "founder@brand.in",
    "name": "Priya",
    "workspace_name": "Brand",
    "plan_id": "pro"
  }'
201application/json
{
  "user_id": "usr_…",
  "invite_url": "https://app.cometly.site/accept-invite?token=…",
  "expires_in_days": 7,
  "workspace_id": "ws_…"
}
GET/admin/users/:id

Account detail, sessions, events and audit

Staff session + 2FA

Path parameters

  • idstringrequired
    User ID
curl "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
PATCH/admin/users/:id

Change name, platform role or status

Staff session + 2FA

Path parameters

  • idstringrequired
    User ID

Body

  • namestring
  • platform_rolestring
    user|support|admin (admin only)
  • statusstring
    active|suspended — suspending signs them out
  • reasonstring
curl -X PATCH "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "suspended",
    "reason": "chargeback"
  }'
200application/json
(empty body)
POST/admin/users/:id/revoke-sessions

Sign out everywhere

Staff session + 2FA

Path parameters

  • idstringrequired
    User ID
curl -X POST "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq/revoke-sessions" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "revoked": 2
}
POST/admin/users/:id/reset-mfa

Reset 2FA

Staff session + 2FA

Path parameters

  • idstringrequired
    User ID
curl -X POST "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq/reset-mfa" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "mfa_enabled": false
}
POST/admin/users/:id/password-reset

Email a password reset (or re-send an invite)

Staff session + 2FA

Path parameters

  • idstringrequired
    User ID
curl -X POST "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq/password-reset" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "sent": "password_reset"
}
POST/admin/users/:id/unlock

Clear a sign-in lockout

Staff session + 2FA

Path parameters

  • idstringrequired
    User ID
curl -X POST "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq/unlock" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "unlocked": true
}
POST/admin/users/:id/impersonate

Start a read-only “view as” session (1 h)

Staff session + 2FA

Path parameters

  • idstringrequired
    User ID

Body

  • reasonstringrequired
    e.g. ticket number — audited
curl -X POST "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq/impersonate" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Ticket #4411"
  }'
200application/json
{
  "session_id": "ses_…",
  "expires_at": "…",
  "read_only": true
}
DELETE/admin/users/:id

Delete an account (restorable 14 days)

Platform admin + 2FA

Path parameters

  • idstringrequired
    User ID
curl -X DELETE "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "deleted": true,
  "purge_after_days": 14,
  "suspended_workspaces": [
    "ws_…"
  ]
}
POST/admin/users/:id/restore

Restore a deleted account

Platform admin + 2FA

Path parameters

  • idstringrequired
    User ID
curl -X POST "https://api.cometly.site/admin/users/usr_5fxw9tcypgsq/restore" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
(empty body)
GET/admin/workspaces

List workspaces

Staff session + 2FA

Query parameters

  • qstring
  • statusstring
  • plan_idstring
curl "https://api.cometly.site/admin/workspaces" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
PATCH/admin/workspaces/:id

Change plan, status or name

Platform admin + 2FA

Path parameters

  • idstringrequired
    Workspace ID

Body

  • plan_idstring
  • statusstring
    active|suspended
  • namestring
  • reasonstring
curl -X PATCH "https://api.cometly.site/admin/workspaces/ws_tg5pvg2u7mwj" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plan_id": "business"
  }'
200application/json
(empty body)
POST/admin/workspaces/:id/credits

Add or deduct credits

Platform admin + 2FA

Path parameters

  • idstringrequired
    Workspace ID

Body

  • deltaintegerrequired
    Positive or negative
  • reasonstringrequired
curl -X POST "https://api.cometly.site/admin/workspaces/ws_tg5pvg2u7mwj/credits" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delta": 500,
    "reason": "Diwali promo"
  }'
200application/json
{
  "balance": 5320,
  "ledger": []
}
GET/admin/plans

List plans

Staff session + 2FA
curl "https://api.cometly.site/admin/plans" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
PATCH/admin/plans/:id

Change plan limits

Platform admin + 2FA

Path parameters

  • idstringrequired
    Plan ID

Body

  • max_domains max_links_month max_api_rpm price_inr nameinteger|string
curl -X PATCH "https://api.cometly.site/admin/plans/pro" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "max_api_rpm": 900
  }'
200application/json
(empty body)
GET/admin/audit

Audit log

Staff session + 2FA

Query parameters

  • actorstring
    e.g. user:usr_…
  • workspace_idstring
  • actionstring
    Prefix, e.g. admin.user
  • beforeinteger
    Cursor
curl "https://api.cometly.site/admin/audit" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
GET/admin/security

Limits, traffic and staff without 2FA

Staff session + 2FA
curl "https://api.cometly.site/admin/security" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
GET/admin/security/events

Security events

Staff session + 2FA

Query parameters

  • typestring
  • severitystring
    info|warning|critical
  • ipstring
    IP or CIDR
  • user_idstring
  • beforeinteger
curl "https://api.cometly.site/admin/security/events" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
GET/admin/security/blocked-ips

Blocked IPs and ranges

Staff session + 2FA
curl "https://api.cometly.site/admin/security/blocked-ips" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
POST/admin/security/blocked-ips

Block an IP or CIDR

Platform admin + 2FA

Body

  • cidrstringrequired
    IPv4 /8+ or IPv6 /16+
  • reasonstringrequired
  • expires_in_minutesinteger
    Omit for permanent
curl -X POST "https://api.cometly.site/admin/security/blocked-ips" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "cidr": "203.0.113.0/24",
    "reason": "Scraping",
    "expires_in_minutes": 1440
  }'
201application/json
(empty body)
DELETE/admin/security/blocked-ips/:id

Unblock

Platform admin + 2FA

Path parameters

  • idstringrequired
    Block ID
curl -X DELETE "https://api.cometly.site/admin/security/blocked-ips/42" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
(empty body)
GET/admin/abuse

Abuse queue, open reports and feed status

Staff session + 2FA

Query parameters

  • statusstring
    pending (default), blocked, cleared, all
curl "https://api.cometly.site/admin/abuse" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
POST/admin/abuse/links/:id/block

Block a link

Staff session + 2FA

Path parameters

  • idstringrequired
    Link ID

Body

  • notestring
    Shown to the workspace
curl -X POST "https://api.cometly.site/admin/abuse/links/lnk_594ufv74rqre/block" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
(empty body)
POST/admin/abuse/links/:id/clear

Mark a link safe (false positive)

Platform admin + 2FA

Path parameters

  • idstringrequired
    Link ID

Body

  • notestring
curl -X POST "https://api.cometly.site/admin/abuse/links/lnk_594ufv74rqre/clear" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
(empty body)
POST/admin/abuse/reports/:id/resolve

Resolve a report

Staff session + 2FA

Path parameters

  • idstringrequired
    Report ID

Body

  • resolutionstring
curl -X POST "https://api.cometly.site/admin/abuse/reports/118/resolve" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
(empty body)
POST/admin/abuse/threats

Add a host or URL to the blocklist

Platform admin + 2FA

Body

  • valuestringrequired
    Host or URL
  • kindstring
    phishing|malware|spam
curl -X POST "https://api.cometly.site/admin/abuse/threats" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "fake-sbi-rewards.top",
    "kind": "phishing"
  }'
201application/json
{
  "listed": "fake-sbi-rewards.top",
  "scanned": 48210,
  "flagged": 0
}
POST/admin/abuse/rescan

Re-scan all links now

Platform admin + 2FA
curl -X POST "https://api.cometly.site/admin/abuse/rescan" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
{
  "scanned": 48210,
  "flagged": 1,
  "deep_checked": 50
}
GET/admin/reputation

Reputation of every domain (worst first)

Staff session + 2FA
curl "https://api.cometly.site/admin/reputation" \
  -b cookies.txt -c cookies.txt
200application/json
(empty body)
POST/admin/reputation/:id/check

Re-check a domain now

Staff session + 2FA

Path parameters

  • idstringrequired
    Domain ID
curl -X POST "https://api.cometly.site/admin/reputation/dom_kd292xv8n8tg/check" \
  -b cookies.txt -c cookies.txt \
  -H "X-CSRF-Token: $CSRF_TOKEN"
200application/json
(empty body)

Public & short-domain endpoints

Served on api.cometly.site without a key, or on every short domain.

GET/health

API health

No auth
curl "https://api.cometly.site/health"
200application/json
{
  "ok": true,
  "db": true,
  "redis": true
}
GET/sdk/attribution.js

Landing-page snippet for conversion tracking

No auth

Stores the cmt_id from the URL in a first-party cookie so your checkout can send it to POST /v1/conversions.

curl "https://api.cometly.site/sdk/attribution.js"
200application/javascript
application/javascript
GET/openapi.json

This reference as OpenAPI 3.1

No auth
curl "https://api.cometly.site/openapi.json"
200application/json
(empty body)
GET/docs

This page

No auth
curl "https://api.cometly.site/docs"
200text/html
text/html
GET/:slugshort domain

Follow a short link

No auth

On any short domain. Redirects (302), or serves a password, deep-link, UPI or preview page. ?qr=1 marks a QR scan and is removed before redirecting; other query parameters are passed to the destination.

Path parameters

  • slugstringrequired
    Case-insensitive
curl -i "https://go.kesari.shop/diwali"
302text/html
302 → Location: https://kesari.shop/diwali  (or an HTML page)
POST/:slugshort domain

Submit a link password

No auth

Path parameters

  • slugstringrequired

Form fields

  • passwordstringrequired
    Form field
curl -X POST -i "https://go.kesari.shop/diwali" \
  --data-urlencode "password=chai2026"
302text/html
302 → Location: https://kesari.shop/diwali  (or an HTML page)
GET/short domain

Bare short domain

No auth

Redirects to the domain’s homepage_url if set.

curl -i "https://go.kesari.shop/"
302text/html
302 → Location: https://kesari.shop/diwali  (or an HTML page)
GET/reportshort domain

Report a harmful link (form)

No auth
curl "https://go.kesari.shop/report"
200text/html
text/html
POST/reportshort domain

Report a harmful link

No auth

Form-encoded. 5 per IP per hour. Three reporters in 7 days put the link in the review queue.

Form fields

  • urlstring
    The short link (or send slug)
  • slugstring
    Instead of url
  • categorystring
    phishing, scam, malware, spam, other
  • reasonstringrequired
    5–2000 chars
  • emailstring
    Optional, for follow-up
curl -X POST "https://go.kesari.shop/report" \
  --data-urlencode "url=https://go.kesari.shop/diwali" \
  --data-urlencode "category=phishing" \
  --data-urlencode "reason=Asks for my bank password"
200text/html
text/html
GET/.well-known/cometly-healthshort domain

Edge reachability probe

No auth
curl "https://go.kesari.shop/.well-known/cometly-health"
200application/json
{
  "ok": true,
  "host": "go.kesari.shop"
}
GET/robots.txtshort domain

robots.txt

No auth
curl "https://go.kesari.shop/robots.txt"
200text/plain
text/plain
GET/favicon.icoshort domain

favicon

No auth
curl "https://go.kesari.shop/favicon.ico"
204No content
(empty body)

No endpoints match your search.