API Endpoints

Complete reference for all available FWURL API endpoints.

Links

Create a Link

Create a new short link.

POST /v1/links

Request Body:

{
  "url": "https://example.com/long-url",
  "customSlug": "my-link",
  "title": "My Link",
  "tags": ["marketing", "campaign"],
  "expiresAt": "2024-12-31T23:59:59Z",
  "domain": "go.yourbrand.com"
}

Parameters:

Field	Type	Required	Description
`url`	string	Yes	Destination URL
`customSlug`	string	No	Custom back-half
`title`	string	No	Link title
`tags`	array	No	Organization tags
`expiresAt`	string	No	ISO 8601 expiration date
`domain`	string	No	Custom domain

Response:

{
  "success": true,
  "data": {
    "id": "abc123",
    "shortUrl": "https://fwurl.com/my-link",
    "longUrl": "https://example.com/long-url",
    "title": "My Link",
    "tags": ["marketing", "campaign"],
    "createdAt": "2024-01-01T00:00:00Z",
    "expiresAt": "2024-12-31T23:59:59Z"
  }
}

Get a Link

Retrieve details for a specific link.

GET /v1/links/:id

Response:

{
  "success": true,
  "data": {
    "id": "abc123",
    "shortUrl": "https://fwurl.com/my-link",
    "longUrl": "https://example.com/long-url",
    "title": "My Link",
    "tags": ["marketing", "campaign"],
    "clicks": 1234,
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

Update a Link

Update an existing link.

PATCH /v1/links/:id

Request Body:

{
  "longUrl": "https://example.com/new-url",
  "title": "Updated Title",
  "tags": ["updated", "tags"]
}

Response:

{
  "success": true,
  "data": {
    "id": "abc123",
    "shortUrl": "https://fwurl.com/my-link",
    "longUrl": "https://example.com/new-url",
    "title": "Updated Title",
    "tags": ["updated", "tags"],
    "updatedAt": "2024-01-02T00:00:00Z"
  }
}

Delete a Link

Delete a link permanently.

DELETE /v1/links/:id

Response:

{
  "success": true,
  "message": "Link deleted successfully"
}

List Links

Get a paginated list of your links.

GET /v1/links

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Results per page (max: 100)
`tag`	string	Filter by tag
`domain`	string	Filter by domain
`search`	string	Search query

Response:

{
  "success": true,
  "data": {
    "links": [
      {
        "id": "abc123",
        "shortUrl": "https://fwurl.com/my-link",
        "longUrl": "https://example.com/long-url",
        "title": "My Link",
        "clicks": 1234,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5
    }
  }
}

Analytics

Get Link Analytics

Retrieve analytics for a specific link.

GET /v1/analytics/:linkId

Query Parameters:

Parameter	Type	Description
`from`	string	Start date (ISO 8601)
`to`	string	End date (ISO 8601)
`group`	string	Group by: hour, day, week, month

Response:

{
  "success": true,
  "data": {
    "totalClicks": 1234,
    "uniqueClicks": 890,
    "clicksByDate": [
      {
        "date": "2024-01-01",
        "clicks": 45
      }
    ],
    "topCountries": [
      {
        "country": "United States",
        "clicks": 567
      }
    ],
    "devices": {
      "desktop": 600,
      "mobile": 500,
      "tablet": 134
    }
  }
}

Domains

List Domains

Get all custom domains.

GET /v1/domains

Response:

{
  "success": true,
  "data": {
    "domains": [
      {
        "id": "dom123",
        "domain": "go.yourbrand.com",
        "verified": true,
        "default": false,
        "createdAt": "2024-01-01T00:00:00Z"
      }
    ]
  }
}

Add a Domain

Add a new custom domain.

POST /v1/domains

Request Body:

{
  "domain": "go.yourbrand.com"
}

Response:

{
  "success": true,
  "data": {
    "id": "dom123",
    "domain": "go.yourbrand.com",
    "verified": false,
    "verificationCode": "fwurl-verify-abc123",
    "dnsRecords": [
      {
        "type": "CNAME",
        "name": "go",
        "value": "custom.fwurl.com"
      },
      {
        "type": "TXT",
        "name": "_fwurl-verification",
        "value": "fwurl-verify-abc123"
      }
    ]
  }
}

QR Codes

Get QR Code

Generate a QR code for a link.

GET /v1/qr/:linkId

Query Parameters:

Parameter	Type	Description
`size`	number	Size in pixels (default: 512)
`format`	string	png, svg, pdf (default: png)
`foreground`	string	Hex color (default: #000000)
`background`	string	Hex color (default: #FFFFFF)

Response:

Returns the QR code image in the specified format.

Rate Limits

All API responses include rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

Error Responses

Error Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

Common Error Codes

Code	Status	Description
`INVALID_API_KEY`	401	API key is invalid or revoked
`MISSING_API_KEY`	401	No API key provided
`INSUFFICIENT_PERMISSIONS`	403	API key lacks required permissions
`NOT_FOUND`	404	Resource not found
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INVALID_URL`	400	URL is invalid
`SLUG_TAKEN`	400	Custom slug already in use
`VALIDATION_ERROR`	400	Request validation failed

Pagination

List endpoints support pagination:

{
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 100,
      "pages": 5,
      "hasNext": true,
      "hasPrev": false
    }
  }
}

Webhooks

Subscribe to link events:

link.created - New link created
link.updated - Link modified
link.deleted - Link removed
link.clicked - Link was clicked

Configure webhooks in Settings > Webhooks.