Redirects API

Manage URL redirect rules with full CRUD operations

Complete reference for managing URL redirects through the REST API.

Overview

The Redirects API allows you to create, read, update, and delete URL redirect rules. All endpoints require authentication using a valid JWT token.

Authentication

All API requests require authentication using a Bearer token in the Authorization header.

Request Headers:

Header	Type	Required	Description
`Authorization`	string	Required	Bearer token for API authentication Example: `Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`
`Content-Type`	string	Required	Media type of the request body (for POST/PUT/PATCH requests) Example: `application/json`

Example:

{
  "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "Content-Type": "application/json"
}

See below for detailed documentation of each endpoint including request/response formats and examples.

POST

/api/v1/redirects

Create Redirect

Creates a new redirect rule.

Request Body

Provide the redirect configuration data.

Parameters:

Parameter	Type	Required	Description
`source`	string	Required	The source URL path to redirect from Example: `/old-page`
`destination`	string	Required	The destination URL path to redirect to Example: `/new-page`
`domain`	string	Optional	The domain for the redirect (optional). Domain-based redirect will redirect to external URL instead of internal path. Example: `example.com`
`statusCode`	number	Required	HTTP status code for the redirect (e.g., 301, 302) Example: `301`
`enabled`	boolean	Required	Whether the redirect is active or not Example: `true`

Example:

{
  "source": "/old-page",
  "destination": "/new-page",
  "domain": "example.com",
  "statusCode": 301,
  "enabled": true
}

Response Structure

Response format and possible status codes for creating a redirect.

201 Created

Created. Redirect created successfully.

Example Response:

{
  "message": "Redirect created successfully",
  "location": "/redirects/1"
}

400 Bad Request

Bad Request. Invalid request body or validation error.

Example Response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body or validation error",
    "details": "source field is required"
  }
}

409 Conflict

Conflict. Redirect already exists (duplicate source URL).

Example Response:

{
  "error": {
    "code": "CONFLICT",
    "message": "Redirect already exists (duplicate source URL)"
  }
}

GET

/api/v1/redirects

Get Redirects

Retrieves all existing redirects in the system with pagination support.

Pagination Parameters

Control pagination behavior and sorting options.

Available Parameters:

Parameter	Type	Required	Default	Description
`paginationType`	string	Optional	`offset`	Pagination type offset or cursor Example: `offset`
`page`	number	Optional	`1`	Page number for offset pagination min: 1 Example: `1`
`limit`	number	Optional	`10`	Items per page for offset pagination min: 1, max: 100 Example: `10`
`cursor`	string	Optional	`null`	Cursor for cursor pagination Example: `eyJpZCI6MTB9`
`first`	number	Optional	`10`	Number of items for cursor pagination min: 1, max: 100 Example: `10`
`sortBy`	string	Optional	`id`	Sort field id, createdAt, updatedAt, source, destination Example: `createdAt`
`sortOrder`	string	Optional	`asc`	Sort order asc or desc Example: `desc`

Example Request:

GET /api/v1/redirects?page=1&limit=10&sortBy=createdAt&sortOrder=desc

Filtering Parameters

Filter redirects based on various criteria.

Available Parameters:

Parameter	Type	Required	Default	Description
`statusCode`	string	Optional	-	Filter by status code Example: `301,302`
`statusCodeOp`	string	Optional	`eq`	Status code operator eq, ne, in, notIn Example: `in`
`source`	string	Optional	-	Filter by source URL path Example: `/old-page`
`sourceOp`	string	Optional	`eq`	Source operator eq, ne, contains, startsWith, endsWith Example: `contains`
`destination`	string	Optional	-	Filter by destination URL path Example: `/new-page`
`destinationOp`	string	Optional	`eq`	Destination operator eq, ne, contains, startsWith, endsWith Example: `startsWith`

Example Request:

GET /api/v1/redirects?statusCode=301,302&statusCodeOp=in&source=/old&sourceOp=startsWith

Response (Offset Pagination)

Response structure for offset-based pagination.

200 OK

Successfully retrieved redirects with pagination data.

Example Response:

{
  "data": [
    {
      "id": 1,
      "source": "/old-page",
      "destination": "/new-page",
      "domain": "example.com",
      "statusCode": 301,
      "createdAt": "2025-12-11T17:23:00.000Z",
      "updatedAt": "2025-12-11T17:23:00.000Z",
      "enabled": true,
      "isCaseSensitive": false
    }
  ],
  "pagination": {
    "total": 100,
    "page": 1,
    "limit": 10,
    "hasNext": true,
    "hasPrev": false
  }
}

400 Bad Request

Bad Request. Invalid query parameters.

Example Response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid query parameters",
    "details": "page must be a positive integer"
  }
}

PUT

/api/v1/redirects/:id

Update Redirect

Completely updates an existing redirect with new values. All fields are required.

Path Parameters

URL path parameters required for this endpoint.

Required Parameters:

Parameter	Type	Required	Description
`id`	number	Required	The unique identifier of the redirect Example: `1`

Example URL:

PUT /api/v1/redirects/1

Request Body

Provide complete redirect data to replace existing redirect. All fields are required.

Parameters:

Parameter	Type	Required	Description
`source`	string	Required	The source URL path to redirect from Example: `/updated-old-page`
`destination`	string	Required	The destination URL path to redirect to Example: `/updated-new-page`
`domain`	string	Optional	The domain for the redirect (optional). Domain-based redirect will redirect to external URL instead of internal path. Example: `example.com`
`statusCode`	number	Required	HTTP status code for the redirect (e.g., 301, 302) Example: `302`
`enabled`	boolean	Required	Whether the redirect is active or not Example: `true`

Example:

{
  "source": "/updated-old-page",
  "destination": "/updated-new-page",
  "domain": "example.com",
  "statusCode": 302,
  "enabled": true
}

Response Structure

Response format and possible status codes for updating a redirect.

200 OK

OK. Redirect updated successfully.

Example Response:

{
  "message": "Redirect updated successfully",
  "location": "/redirects/1"
}

400 Bad Request

Bad Request. Invalid request body or validation error.

Example Response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body or validation error"
  }
}

404 Not Found

Not Found. Redirect with specified ID not found.

Example Response:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Redirect with specified ID not found"
  }
}

409 Conflict

Conflict. Updated redirect conflicts with existing redirect.

Example Response:

{
  "error": {
    "code": "CONFLICT",
    "message": "Updated redirect conflicts with existing redirect"
  }
}

PATCH

/api/v1/redirects/:id

Patch Redirect

Partially updates an existing redirect. Only provided fields are updated.

Path Parameters

URL path parameters required for this endpoint.

Required Parameters:

Parameter	Type	Required	Description
`id`	number	Required	The unique identifier of the redirect Example: `1`

Example URL:

PATCH /api/v1/redirects/1

Request Body (all fields optional)

Provide only the fields you want to update.

Parameters:

Parameter	Type	Required	Description
`destination`	string	Optional	The destination URL path to redirect to Example: `/partially-updated-page`
`enabled`	boolean	Optional	Whether the redirect is active or not Example: `false`

Example:

{
  "destination": "/partially-updated-page",
  "enabled": false
}

Response Structure

Response format and possible status codes for partially updating a redirect.

200 OK

OK. Redirect updated successfully.

Example Response:

{
  "message": "Redirect updated successfully",
  "location": "/redirects/1"
}

400 Bad Request

Bad Request. Invalid request body or validation error.

Example Response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body or validation error"
  }
}

404 Not Found

Not Found. Redirect with specified ID not found.

Example Response:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Redirect with specified ID not found"
  }
}

409 Conflict

Conflict. Updated redirect conflicts with existing redirect.

Example Response:

{
  "error": {
    "code": "CONFLICT",
    "message": "Updated redirect conflicts with existing redirect"
  }
}

DELETE

/api/v1/redirects/:id

Delete Redirect

Deletes a specific redirect by its ID.

Path Parameters

URL path parameters required for this endpoint.

Required Parameters:

Parameter	Type	Required	Description
`id`	number	Required	The unique identifier of the redirect to delete Example: `1`

Example URL:

DELETE /api/v1/redirects/1

Response Structure

Response format and possible status codes for deleting a redirect.

204 Response

No Content. Redirect deleted successfully (empty response body).

400 Bad Request

Bad Request. Invalid redirect ID format.

Example Response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid redirect ID format"
  }
}

404 Not Found

Not Found. Redirect with specified ID not found.

Example Response:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Redirect with specified ID not found"
  }
}

POST

/api/v1/redirects/batch

Batch Create Redirects

Creates multiple redirect rules in a single request.

Request Body

Provide an array of redirect configurations to create.

Parameters:

Parameter	Type	Required	Description
`redirects`	array	Required	Array of redirect objects to create Example: `[{...}, {...}]`

Example:

{
  "redirects": [
    {
      "source": "/old-page-1",
      "destination": "/new-page-1",
      "domain": "example.com",
      "statusCode": 301,
      "enabled": true
    },
    {
      "source": "/old-page-2",
      "destination": "/new-page-2",
      "statusCode": 302,
      "enabled": true
    }
  ]
}

Response Structure

Response format and possible status codes for batch creating redirects.

201 Created

Created. All redirects created successfully.

Example Response:

{
  "message": "All redirects created successfully.",
  "createdRedirects": [
    {
      "message": "Redirect created successfully",
      "location": "/redirects/1"
    }
  ],
  "createdCount": 1
}

207 Response

Multi-Status. Some redirects were invalid and were not created.

Example Response:

{
  "message": "Some redirects were invalid and were not created",
  "createdRedirects": [],
  "createdCount": 0,
  "errors": [
    "Invalid redirect data"
  ]
}

400 Bad Request

Bad Request. Invalid request body, empty array, or all redirects invalid.

Example Response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body, empty array, or all redirects invalid"
  }
}

PATCH

/api/v1/redirects/batch

Batch Update Redirects

Partially updates multiple redirect rules in a single request. Only provided fields are updated for each redirect.

Request Body

Provide an array of redirect objects with ID and fields to update.

Parameters:

Parameter	Type	Required	Description
`redirects`	array	Required	Array of redirect objects with ID and fields to update Example: `[{id: 1, destination: '/new-dest', enabled: false}]`

Example:

{
  "redirects": [
    {
      "id": 1,
      "destination": "/updated-page-1",
      "enabled": false
    },
    {
      "id": 2,
      "statusCode": 302,
      "enabled": true
    }
  ]
}

Response Structure

Response format and possible status codes for batch updating redirects.

200 OK

OK. All redirects updated successfully.

Example Response:

{
  "message": "All redirects updated successfully.",
  "updatedRedirects": [
    {
      "message": "Redirect updated successfully",
      "id": 1,
      "location": "/redirects/1"
    }
  ],
  "updatedCount": 1
}

207 Response

Multi-Status. Some redirects could not be updated.

Example Response:

{
  "message": "Some redirects could not be updated",
  "updatedRedirects": [],
  "updatedCount": 0,
  "errors": [
    "Redirect not found"
  ]
}

400 Bad Request

Bad Request. Invalid request body, empty array, or all updates invalid.

Example Response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body, empty array, or all updates invalid"
  }
}

DELETE

/api/v1/redirects/batch

Batch Delete Redirects

Deletes multiple redirect rules in a single request.

Request Body

Provide an array of redirect IDs to delete.

Parameters:

Parameter	Type	Required	Description
`ids`	array	Required	Array of redirect IDs to delete Example: `[1, 2, 3, 4]`

Example:

{
  "ids": [
    1,
    2,
    3,
    4
  ]
}

Response Structure

Response format and possible status codes for batch deleting redirects.

200 OK

OK. Redirects deleted successfully.

Example Response:

{
  "message": "Redirects deleted successfully",
  "deletedCount": 4
}

400 Bad Request

Bad Request. Invalid request body or empty IDs array.

Example Response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body or empty IDs array"
  }
}