URL Shortener API Documentation

Customer-facing API payloads, parameters, error codes, and examples for creating, listing, and opening short URLs.

Authentication & Base URL

The create (POST) and search (GET) APIs require a valid customer access token via the Authorization: Bearer <access_token> header. The public redirect endpoint does not require authentication.

Base URL:https://csvc.mbdt01.com/api/v1/url-shortner

1. POST: Create Short URL

Endpoint: POST /api/v1/url-shortner/

Request Parameters

Field	Type	Required	Description
`longUrl`	string	Yes	The destination URL to shorten. Must be a valid HTTP or HTTPS URL.
`basePath`	string	No	Optional custom short-link domain or base path.
`omitProtocol`	boolean	No	When true, the returned short URL omits http:// or https:// from the short-link base.
`ttl`	number	No	Number of days before the short URL expires. This can be set between 1-365 days by passing the ttl value. Default is 30.

Example Request

      curl --request POST "https://csvc.mbdt01.com/api/v1/url-shortner/" \
      --header "Authorization: Bearer <access_token>" \
      --header "Content-Type: application/json" \
      --data '{
      "longUrl": "https://example.com/campaign/landing?page=1",
      "ttl": 30
      }'
    

Example Response (200 OK)

      {
      "_id": "64a1...",
      "urlCode": "B1x2y3z4a",
      "longUrl": "https://example.com/campaign/landing?page=1",
      "shortUrl": "https://mb1.io/B1x2y3z4a",
      "paid": 302,
      "createdAt": "2026-06-15T10:00:00.000Z",
      "expiresAt": "2026-07-15T10:00:00.000Z"
      }
    

2. GET: List Short URLs

Endpoint: GET /api/v1/url-shortner/search

Example Request

      curl --request GET "https://csvc.mbdt01.com/api/v1/url-shortner/search"
      \
      --header "Authorization: Bearer <access_token>"
    

Example Response (200 OK)

      [
      {
      "_id": "64a1...",
      "urlCode": "B1x2y3z4a",
      "longUrl": "https://example.com/campaign/landing?page=1",
      "shortUrl": "https://mb1.io/B1x2y3z4a",
      "paid": 302,
      "createdAt": "2026-06-15T10:00:00.000Z",
      "expiresAt": "2026-07-15T10:00:00.000Z"
      }
      ]
    

3. GET: Open Short URL

Endpoint: GET /api/v1/url-shortner/{code}

Example Request

      curl --request GET "https://csvc.mbdt01.com/api/v1/url-shortner/B1x2y3z4a"
    

Successful Response Behavior

When called through the API Gateway, the service returns a 302 Found status and redirects the browser or client to the original longUrl destination.

Standard API Error Codes

These are the HTTP status codes returned when a request cannot be processed successfully.

HTTP Status	Example Body	Meaning
400	`{ "error": "invalid Long Url" }` or `{ "error": "invalid Base Url" }`	The supplied `longUrl` or configured `basePath` is missing or fails validation. Can also occur if required fields are missing (Joi validation error).
401	`{ "message": "Unauthorized" }`	The access token is missing, invalid, or expired.
404	`Not found` or `[]`	The short code does not exist, or no short URL records were found for the project.
410	`URL Expired`	The short URL exists but its expiration date has passed.
500	Empty or generic error response	An unexpected server-side error occurred.

Need More Help?

If you've followed the steps above and are still having trouble implementing the API, our support team is ready to assist you.

Contact Support Submit a ticket to our team for personalized help.