REST API

API Reference

Manage your domain redirects, short URLs, and API keys programmatically.

Base URL | https://app.forwardto.xyz/api

Authentication

All API endpoints require authentication. Two methods are supported: the Authorization header (for JWT tokens) and the X-API-Key header (for API keys).

Bearer token (Auth0 JWT)

For browser-based or interactive use. Obtain a token from the Auth0 flow.

Authorization: Bearer <access_token>

API key

For programmatic access. Create a key in the dashboard under API Keys. All ForwardTo.xyz keys are prefixed with fwd_ so you can easily identify them.

X-API-Key: fwd_<your_api_key>

Domains

GET /api/domains List all domains

Returns all domain redirects belonging to the authenticated user.

Response 200

[
  {
    "_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "hostname": "go.example.com",
    "to": "https://destination.com",
    "code": 302,
    "type": "path",
    "redirects": 42,
    "user": "auth0|abc123",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-06-01T12:00:00.000Z"
  }
]

GET /api/domains/:id Get a domain

Path parameters

Parameter	Type	Description
id	string	MongoDB ObjectId

Response 200 — Domain object (see above)

Response 404

{ "message": "Domain not found." }

POST /api/domains Create a domain

Request body

Field	Type	Required	Description
hostname	string	Yes	Source hostname (e.g. `go.acme.com`)
to	string	No*	Redirect destination URL. Required for `domain` and `path` types; omit for `shortener`.
code	number	No	`301` or `302` (default `302`)
type	string	No	`"domain"`, `"path"`, or `"shortener"` (default `"domain"`)

type: "path" appends the incoming request path to the destination URL. type: "domain" redirects to the destination URL as-is. type: "shortener" turns the domain into a URL shortener host — to is not used; manage short links via the Short URLs endpoints.

Example

{
  "hostname": "go.acme.com",
  "to": "https://destination.com",
  "code": 302,
  "type": "path"
}

Response 201 — Created domain object

PUT /api/domains/:id Update a domain

Path parameters

Parameter	Type	Description
id	string	MongoDB ObjectId

Request body — same fields as Create a domain.

Response 200 — Updated domain object

DELETE /api/domains/:id Delete a domain

Path parameters

Parameter	Type	Description
id	string	MongoDB ObjectId

Response 200

{ "message": "Domain deleted!", "success": true }

Short URLs

Short URLs belong to a domain of type shortener. Each short URL maps a unique code (e.g. abc123) to a destination URL. Visiting s.example.com/abc123 redirects the visitor to the destination.

GET /api/short-urls List short URLs

Returns all short URLs belonging to the authenticated user.

Query parameters

Parameter	Type	Description
domainId	string	Optional. Filter by shortener domain ObjectId.

Response 200

[
  {
    "_id": "665abc456def",
    "code": "abc123",
    "to": "https://very-long-destination.com/some/path",
    "domain": "664abc123",
    "hostname": "s.example.com",
    "httpCode": 302,
    "redirects": 27,
    "createdAt": "2024-06-01T00:00:00.000Z",
    "updatedAt": "2024-06-01T00:00:00.000Z"
  }
]

GET /api/short-urls/:id Get a short URL

Path parameters

Parameter	Type	Description
id	string	MongoDB ObjectId of the short URL

Response 200 — Short URL object (see above)

Response 404

{ "message": "Short URL not found." }

POST /api/short-urls Create a short URL

The referenced domain must exist, be owned by the authenticated user, and have type: "shortener".

Request body

Field	Type	Required	Description
domainId	string	Yes	ObjectId of the shortener domain
to	string	Yes	Destination URL
code	string	No	Custom short code. A 6-character hex code is auto-generated if omitted.
httpCode	number	No	`301` or `302` (default `302`).

Example

{
  "domainId": "664abc123",
  "to": "https://very-long-destination.com/some/path",
  "code": "sale"
}

Response 201 — Created short URL object

Response 409

{ "message": "A short URL with that code already exists on this domain." }

PUT /api/short-urls/:id Update a short URL

Request body

Field	Type	Description
code	string	New short code
to	string	New destination URL
httpCode	number	`301` or `302`. Omit to leave unchanged.

Response 200 — Updated short URL object

Response 409

{ "message": "A short URL with that code already exists on this domain." }

DELETE /api/short-urls/:id Delete a short URL

Response 200

{ "message": "Short URL deleted!", "success": true }

Response 404

{ "message": "Short URL not found." }

Metrics

Click analytics for domains and short URLs. The optional domainId filter accepts either a Domain _id or a Short URL _id.

GET /api/metrics Redirect counts over time

Returns redirect counts bucketed by day, week, or month for the given period.

Query parameters

Parameter	Default	Description
period	`day`	`day` (last 30 days), `week` (last 12 weeks), `month` (last 12 months)
domainId	—	Filter to a specific Domain or Short URL ObjectId

Response 200

[
  { "date": "2024-06-01", "count": 42 },
  { "date": "2024-06-02", "count": 18 }
]

GET /api/metrics/referrers Top referrers

Returns the top 20 referring hostnames for the selected period. Clicks with no Referer header appear as Direct.

Query parameters

Same as /api/metrics.

Response 200

[
  { "referrer": "twitter.com", "count": 84 },
  { "referrer": "Direct", "count": 31 }
]

API Keys

GET /api/keys List API keys

Returns all API keys belonging to the authenticated user. The raw key value is never returned after creation.

Response 200

[
  {
    "_id": "64a1b2c3d4e5f6a7b8c9d0e2",
    "name": "My CI pipeline",
    "keyPreview": "fwd_a1b2c3d4...",
    "user": "auth0|abc123",
    "lastUsedAt": "2024-06-01T12:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-06-01T12:00:00.000Z"
  }
]

POST /api/keys Create an API key

Generates a new API key. The full key value is returned only once — store it securely. All keys are prefixed with fwd_.

Request body

Field	Type	Required	Description
name	string	Yes	Human-readable label for the key

Example

{ "name": "My CI pipeline" }

Response 201

{
  "_id": "64a1b2c3d4e5f6a7b8c9d0e2",
  "name": "My CI pipeline",
  "keyPreview": "fwd_a1b2c3d4...",
  "key": "fwd_a1b2c3d4e5f6...",
  "createdAt": "2024-01-01T00:00:00.000Z"
}

The key field is only present in this response and cannot be retrieved again.

DELETE /api/keys/:id Delete an API key

Immediately revokes the API key.

Path parameters

Parameter	Type	Description
id	string	MongoDB ObjectId

Response 200

{ "message": "API key deleted!", "success": true }

Response 404

{ "message": "API key not found." }

Errors

All errors follow the same JSON structure:

{
  "message": "Human-readable error description",
  "status": 401
}

Status	Meaning
400	Bad request — missing or invalid parameters
401	Unauthorized — missing or invalid credentials
403	Forbidden — resource belongs to another user
404	Not found
409	Conflict — duplicate hostname or short code
429	Too many requests — rate limit exceeded (200 req / 15 min)
500	Internal server error