Developer API

Use the Developer API when an approved backend service needs to create, organize, update, measure, or automate URLNow short links.

The Developer API uses a developer API key from the Developer console. Store the key server-side and restrict access to authorized systems.

API capability

The Developer API supports short-link creation plus v2 Power Tools workflows for campaigns, bulk operations, conversions, webhooks, saved dashboard views, and reporting.

Use Dashboard for manual link creation. Use Power Tools and the developer endpoints below for approved automation and integrations.

Before you start

1. Create a URLNow account from Register.
2. Open the Developer console.
3. Submit a developer access request.
4. Wait for approval.
5. Create a developer API key.
6. Store the key securely on your server.

Do not place developer API keys in browser JavaScript, mobile apps, public repositories, or any place users can inspect.

Base URL

https://urlnow.me/api

Send this header with requests:

Accept: application/json
Authorization: Bearer YOUR_DEVELOPER_KEY

Create a short link

POST /api/short-url

curl -X POST https://urlnow.me/api/short-url \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_DEVELOPER_KEY" \
  -d "long_url=https://example.com/product" \
  -d "alias=product-launch"

Request fields

If alias is left blank, URLNow creates a custom ending automatically.

Successful response

{
  "success": true,
  "url": {
    "long_url": "https://example.com/product",
    "alias": "product-launch",
    "shorten_url": "https://urlnow.me/product-launch"
  }
}

Power Tools API v2

The v2 surface keeps the same base URL and bearer key, then adds business workflows for listing, organizing, measuring, and automating links. Approved developers can also manage these workflows from the Power Tools console at /app/developer/power-tools.

Short URL lifecycle

GET /api/short-urls supports page, per_page, campaign, campaign_id, tag, source, search, include_archived, and archived=only.

Campaigns and bulk actions

Bulk move example:

curl -X POST https://urlnow.me/api/short-urls/bulk \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_DEVELOPER_KEY" \
  -d "action=move" \
  -d "campaign_id=123" \
  -d "ids[]=456"

Conversion tracking

Use POST /api/conversions for server-side conversion events and /api/conversion-pixel/{alias}.gif for browser pixel tracking.

Server-side conversion example:

curl -X POST https://urlnow.me/api/conversions \
  -H "Accept: application/json" \
  -H "Authorization: Bearer YOUR_DEVELOPER_KEY" \
  -d "alias=product-launch" \
  -d "event_name=signup" \
  -d "event_id=signup-123" \
  -d "value=49" \
  -d "currency=USD"

event_id is idempotent. Send the same event ID on retries to avoid duplicate conversion rows.

Pixel example:

<img src="https://urlnow.me/api/conversion-pixel/product-launch.gif?event_name=lead" width="1" height="1" alt="">

Webhooks

Webhook endpoints receive queued delivery records for link.created, link.updated, link.clicked, link.disabled, and conversion.created.

Automation and growth

Phase 2 adds automation and team workflow endpoints while pricing remains disabled.

The Power Tools console can create read-only analytics share links. Public share URLs are served under /share/analytics/{token}, are marked noindex, can expire, and can be revoked from the console. Anyone with the share URL can view the report until it expires or is revoked.

Scheduled automation is handled by powertools:run-automation. Webhook delivery is handled by powertools:deliver-webhooks. Weekly digest generation uses powertools:weekly-digest, and worker health checks use powertools:worker-health or GET /api/worker-health. Webhook deliveries include X-URLNow-Signature, X-URLNow-Timestamp, X-URLNow-Event, and X-URLNow-Delivery headers.

Custom ending rules

Custom endings:

• Must be unique.
• Must use 3 to 64 characters.
• May contain letters, numbers, hyphens, and underscores.
• Cannot use reserved platform words such as app, api, login, register, pricing, features, organizations, qr-code-generator, or docs.

Choose custom endings that are short, readable, and meaningful for your campaign or workflow.

Link safety

URLNow validates destinations before creating short links. A request may be rejected if the destination is:

• Missing or invalid.
• A private or local address.
• Blocked by safety checks.
• Too long.

Developer key approval

Developer keys work only when the account's developer access request is approved.

If access is pending, rejected, or revoked, requests with that key will not create short links.

Common errors

Integration checklist

• Request approval before launching an integration.
• Keep the developer API key on your server only.
• Validate destination URLs in your app before sending them to URLNow.
• Handle 403, 404, 422, and 500 responses.
• Rotate the key from the developer console if it may have been exposed.
• Use descriptive custom endings for campaign and customer-facing links.