API overview

The Public Url API is a REST API served by the API gateway. All product operations available in the dashboard — links, domains, campaigns, analytics, reports, webhooks — are available programmatically.

Interactive reference

Every endpoint, parameter, schema, and example is documented in the API reference — grouped by resource, with code samples in seven languages and a playground to try requests directly from your browser.

Base URL

https://api.publicurl.in/v1

Self-hosted deployments expose the gateway on their own origin; locally it listens on http://localhost:4000/v1.

Authentication

Every endpoint is authenticated with an API key — create keys in the dashboard under Settings → API keys (or via POST /v1/api-keys) and send them as a bearer credential:

curl https://api.publicurl.in/v1/links \
  -H "Authorization: Bearer pu_your_api_key"

Keys can carry scopes and are scoped to the user (and, through the active workspace, to an organization). Browser sessions authenticated with a cookie are used automatically by the dashboard, but programmatic access always uses an API key.

The gateway validates the key, resolves the workspace and role, and forwards identity headers (x-user-id, x-workspace-id, x-role) to internal services. Keys are stored hashed, support IP allow-lists, and record last-used timestamps.

Response envelope

Responses use a consistent envelope with a data payload and request metadata:

{
  "data": [],
  "meta": { "requestId": "req_01J..." }
}

Errors are normalized by the gateway and include the request ID, which is also returned in the x-request-id response header — include it when reporting issues.

Rate limits

Coarse rate limits apply at the gateway, with stricter tiers on auth and event-ingestion routes. Rate-limit responses return 429 with retry guidance. If you need higher throughput for bulk operations, contact support.

Endpoint map

Resource	Endpoints	Notes
Links	`GET/POST /links`, `PATCH /links/{id}`	Create, list, and update short links.
Link preview	`GET /links/preview?url=...`	Unfurl a destination before linking.
Domains	`GET/POST /domains`	Branded domains and DNS verification.
Analytics	`GET /analytics/*`	Metrics, timeseries, and breakdowns.
Campaigns	`GET/POST /campaigns`	Campaign management.
UTM templates	`GET/POST /utm-templates`	Reusable UTM presets.
Reports	`GET/POST /reports`	Report definitions and exports.
Webhooks	`GET/POST /webhooks`	Subscriptions and delivery logs.
Media	`POST /media`, `GET /media/{id}/content`	Asset uploads and content.
Bio pages	`GET/POST /bio-pages`	Bio page management.
Plans and billing	`GET /plans`, `/billing/*`	Subscription management.
API keys	`GET/POST /api-keys`	Key lifecycle (session auth only).
Audit log	`GET /audit-log`	Workspace activity trail.
Security log	`GET /security-log`	Account security events.
Deferred deep links	`POST /deferred/resolve`	Resolve deferred deep-link matches.
GeoIP	`GET /geoip`	Geo lookup for the caller.
Public dashboards	`GET /public/dashboards/{token}`	Unauthenticated shared dashboards.

The interactive OpenAPI reference for auth routes is served by the auth service at /v1/auth/reference.

Webhooks

To receive events instead of polling, subscribe an HTTPS endpoint to events like link.created, click.received, and conversion.received. Every delivery is signed and retried with exponential backoff. See Webhooks for the full reference.