Docs/API Reference

API Reference

Complete API documentation for programmatic link management

Internal Documentation: For comprehensive API implementation details, database schemas, and security notes, see API_REFERENCE.md in the project root.

Authentication

All API requests require authentication using an API key. Generate your API key in the Dashboard.

# Include your API key in the Authorization header

Authorization: Bearer sk_live_your_api_key_here

Base URL

https://edgeurl.io/api

Rate Limits

Link Creation: 5 requests per minute per API key
Link Retrieval: 20 requests per 10 seconds per IP

Rate limit headers are included in all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

POST

/api/links

Create a new short link.

Request Body

{ "target_url": "https://example.com/page", "custom_slug": "my-link", // Optional "expires_at": "2024-12-31T23:59:59Z", // Optional "meta": { // Optional "campaign": "summer-sale" } }

Response (201 Created)

{ "id": "uuid", "slug": "my-link", "short_url": "https://0gr.me/my-link", "target_url": "https://example.com/page", "created_at": "2024-01-01T00:00:00Z" }

cURL Example

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

GET

/api/links

Retrieve all links for your organization.

Query Parameters

page - Page number (default: 1)
limit - Results per page (default: 50, max: 100)

Response (200 OK)

{ "links": [ { "id": "uuid", "slug": "abc123", "short_url": "https://0gr.me/abc123", "target_url": "https://example.com/page", "is_active": true, "total_clicks": 42, "created_at": "2024-01-01T00:00:00Z", "expires_at": null } ], "pagination": { "page": 1, "limit": 50, "total": 100, "total_pages": 2 } }

cURL Example

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

GET

/api/links/:id

Retrieve a specific link by ID.

Response (200 OK)

{ "id": "uuid", "slug": "abc123", "short_url": "https://0gr.me/abc123", "target_url": "https://example.com/page", "is_active": true, "total_clicks": 42, "created_at": "2024-01-01T00:00:00Z", "expires_at": null }

PATCH

/api/links/:id

Update a link's target URL or metadata.

Request Body

{ "target_url": "https://example.com/new-page", // Optional "is_active": false // Optional }

Note: The slug cannot be changed after creation.

DELETE

/api/links/:id

Permanently delete a link.

Response (200 OK)

{ "message": "Link deleted successfully" }

Warning: This action is irreversible. All analytics data for this link will be preserved but the short link will stop working immediately.

Error Responses

Common Error Codes

400 Bad Request

Invalid request body or parameters

401 Unauthorized

Missing or invalid API key

403 Forbidden

Plan limit exceeded or insufficient permissions

404 Not Found

Resource not found

429 Too Many Requests

Rate limit exceeded

Next Steps

→ Generate an API Key → Learn Core Concepts → Quick Start Guide