API Reference

Programmatic access to EdgeURL link management

Base URL

https://edgeurl.io/api

Authentication

All API requests require an API key. Create one in your dashboard. Include your key in the Authorization header:

Request Header

Authorization: Bearer sk_live_your_api_key_here
Content-Type: application/json

Security Note

- Store API keys in environment variables, never in code
- API keys are shown only once when created - save them securely
- Use the Regenerate feature if you need a new key
- Apply minimum permissions needed for your use case

Permissions

API keys can have different permission levels:

read

View links, analytics, and account data

write

Create and update links

delete

Delete links and resources

admin

Full access including API key management

Links

GET

/api/links

List all links with pagination

read

POST

/api/links

Create a new short link

write

GET

/api/links/:id

Get a specific link by ID

read

PATCH

/api/links/:id

Update a link

write

DELETE

/api/links/:id

Delete a link

delete

GET

/api/links/:id/analytics

Get link analytics

read

Create Link

POST /api/links

curl -X POST https://edgeurl.io/api/links \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com/my-long-url",
    "custom_slug": "my-link"
  }'

Request body parameters:

Parameter	Type	Description
target_url	string	Required. The destination URL
custom_slug	string	Optional. Custom short code (3-50 chars)
expires_at	string	Optional. ISO 8601 expiration date
custom_domain_id	string	Optional. UUID of verified custom domain

Response (201 Created)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "slug": "my-link",
  "short_url": "https://0gr.me/my-link",
  "target_url": "https://example.com/my-long-url",
  "created_at": "2025-12-09T08:00:00.000Z"
}

List Links

GET /api/links

curl https://edgeurl.io/api/links?page=1&limit=50 \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "links": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "slug": "my-link",
      "short_url": "https://0gr.me/my-link",
      "target_url": "https://example.com",
      "is_active": true,
      "total_clicks": 142,
      "created_at": "2025-12-09T08:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "active": 1,
    "total_pages": 1
  }
}

Update Link

PATCH /api/links/:id

curl -X PATCH https://edgeurl.io/api/links/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://example.com/new-destination",
    "is_active": false
  }'

Delete Link

DELETE /api/links/:id

curl -X DELETE https://edgeurl.io/api/links/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer sk_live_your_key"

Analytics

GET

/api/links/:id/analytics

Get detailed analytics for a link

read

GET

/api/dashboard/stats

Get account-wide statistics

read

Link Analytics

GET /api/links/:id/analytics

curl https://edgeurl.io/api/links/550e8400-e29b-41d4-a716-446655440000/analytics \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "link": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "slug": "my-link",
    "short_url": "https://0gr.me/my-link",
    "target_url": "https://example.com",
    "total_clicks": 142,
    "created_at": "2025-12-09T08:00:00.000Z"
  },
  "daily_clicks": [
    { "date": "2025-12-09", "clicks": 42 },
    { "date": "2025-12-08", "clicks": 100 }
  ],
  "summary": {
    "total_clicks": 142,
    "days_active": 2,
    "average_clicks_per_day": 71
  }
}

Dashboard Stats

GET /api/dashboard/stats

curl https://edgeurl.io/api/dashboard/stats \
  -H "Authorization: Bearer sk_live_your_key"

Response

{
  "stats": {
    "total_clicks": 1542,
    "total_links": 25,
    "active_links": 23,
    "clicks_this_month": 890,
    "clicks_this_week": 245,
    "clicks_today": 42
  }
}

Error Handling

The API returns standard HTTP status codes and JSON error responses:

Status	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions or plan limit reached
404	Not Found - Resource does not exist
409	Conflict - Slug already exists
429	Rate Limited - Too many requests
500	Server Error

Error Response Example

{
  "error": "Slug already exists. Choose a different slug."
}

Rate Limits

API requests are rate limited based on your plan. Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1702108800

Ready to Get Started?

Create an API key and start building with EdgeURL

Create API Key