Kutt Getting Started: API Access and First Request (2026)

Getting started overview

Integrating with Kutt's API for URL shortening and management involves a series of steps, beginning with account creation and API key generation. Kutt provides a RESTful API that supports operations such as creating short links, managing custom domains, and retrieving link analytics. The API uses API keys for authentication, which are generated from the user dashboard.

This guide outlines the process for new users to set up their Kutt account, obtain the necessary API credentials, and execute a basic API request to shorten a URL. Kutt offers a free tier that includes up to 500 links and 50,000 clicks per month, allowing developers to test functionality before committing to a paid plan. The primary method for interacting with the Kutt API is via HTTP requests, typically using JSON payloads for data exchange.

Here is a quick reference for the initial setup:

Create an account and get keys

Before making any API calls, you must create a Kutt account and generate an API key. The API key serves as your credential for authenticating requests to the Kutt API.

Account Creation

1. Navigate to the Kutt homepage.
2. Click on the 'Sign Up' or 'Get Started' button.
3. Follow the prompts to register for a new account. This typically involves providing an email address and creating a password.
4. Verify your email address if required by Kutt.

API Key Generation

1. Log in to your newly created Kutt account.
2. From your Kutt dashboard, locate the 'Settings' or 'Account Settings' section.
3. Within the settings, find the 'API Keys' or 'Developer Settings' tab.
4. Click on a button or link to 'Generate New API Key' or 'Create Token'.
5. A unique API key will be displayed. Copy this key immediately, as it may not be shown again for security reasons. Treat your API key as a sensitive credential, similar to a password. Kutt's API documentation specifies that this key must be included in the X-API-Key header for all authenticated requests.

Your first request

Once you have an API key, you can make your first API request to shorten a URL. This example uses cURL, a command-line tool for making HTTP requests, which is widely available on most operating systems. For alternative methods, you could use a programming language's HTTP client library or a dedicated API testing tool like Postman.

API Endpoint

The primary endpoint for shortening URLs is https://kutt.it/api/v2/links.

Request Structure

To shorten a URL, you will send an HTTP POST request to this endpoint with a JSON payload containing the long URL and other optional parameters. The API key must be included in the X-API-Key HTTP header.

Example: Shorten a URL with cURL

Replace YOUR_API_KEY with the actual API key you generated and YOUR_LONG_URL with the URL you wish to shorten.

curl -X POST \
  https://kutt.it/api/v2/links \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY' \
  -d '{
    "target": "YOUR_LONG_URL"
  }'

For instance, to shorten https://developers.google.com/maps:

curl -X POST \
  https://kutt.it/api/v2/links \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -d '{
    "target": "https://developers.google.com/maps"
  }'

Expected Response

A successful request will return a JSON object similar to this, containing the shortened URL and other details:

{
  "id": "clw7j3f5p0000y88888888888",
  "address": "kutt.it/example",
  "link": "https://kutt.it/example",
  "target": "https://developers.google.com/maps",
  "description": null,
  "domain": null,
  "password": null,
  "clicks": 0,
  "createdAt": "2026-05-29T12:00:00.000Z",
  "updatedAt": "2026-05-29T12:00:00.000Z"
}

The link field in the response contains the newly generated shortened URL.

Example: Shortening with a Custom Slug (Optional)

You can also specify a custom slug for your shortened URL by adding the address field to your JSON payload. Make sure the custom slug is available.

curl -X POST \
  https://kutt.it/api/v2/links \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: sk_xxxxxxxxxxxxxxxxxxxxxxxxxx' \
  -d '{
    "target": "https://developers.google.com/maps",
    "address": "google-maps-dev"
  }'

Common next steps

After successfully shortening your first URL, you might explore additional features offered by the Kutt API. These include:

• Custom Domains: Integrate your own custom domain for branded short links. This requires configuration within your Kutt dashboard and DNS settings. Refer to the Kutt documentation for detailed instructions on setting up custom domains.
• Link Management: Use the API to retrieve, update, or delete existing short links. The Kutt API provides endpoints for these operations, allowing programmatic control over your shortened URLs.
• Analytics: Access click analytics for your short links. Kutt tracks various metrics, such as total clicks, referrer information, and geographical data, which can be retrieved via the API.
• QR Codes: Generate QR codes for your short links. This feature can be particularly useful for print media or physical advertisements, enabling easy access to your digital content.
• Rate Limits: Understand and manage API rate limits to ensure your application operates smoothly without hitting usage caps. Kutt's API reference details the specific rate limits for different tiers.
• SDKs: For JavaScript developers, Kutt provides an official JavaScript SDK to simplify integration, abstracting away direct HTTP request handling. This can accelerate development by providing pre-built functions for common API operations.
• Error Handling: Implement robust error handling in your application to gracefully manage failed API requests. The Kutt API returns standard HTTP status codes and JSON error messages to indicate issues such as invalid API keys, missing parameters, or rate limit breaches.
• Webhook Integration: Explore Kutt's webhook capabilities to receive real-time notifications about events such as new link creations or click events. This can be used to trigger automated workflows or update external systems. For general information on webhooks, see the Twilio webhooks guide.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting steps:

1. Check API Key

• Incorrect Key: Ensure your API key is correctly copied and pasted into the X-API-Key header. A single character mismatch will result in authentication failure.
• Expired Key: While Kutt API keys generally do not expire automatically, if you regenerate a key, the old one becomes invalid. Always use the most recently generated key.
• Missing Header: Verify that the X-API-Key header is present in your request. Without it, the API cannot authenticate your identity.

2. Verify Request Body and Headers

• Content-Type Header: The Kutt API expects JSON payloads. Ensure your request includes the header Content-Type: application/json.
• JSON Formatting: Double-check that your JSON payload is valid. Missing commas, unquoted keys, or incorrect syntax will lead to parsing errors. Use a JSON linter if unsure.
• Required Parameters: For shortening a URL, the target field is mandatory. Ensure it is present and contains a valid, fully qualified URL.

3. Review API Endpoint

• Correct URL: Confirm that you are sending the request to the correct endpoint: https://kutt.it/api/v2/links.
• HTTP Method: Ensure you are using the HTTP POST method for creating new short links.

4. Check Network Connectivity

• Internet Connection: Verify that your machine has an active internet connection and can reach kutt.it.
• Firewall/Proxy: If you are on a corporate network, firewalls or proxy servers might be blocking outbound requests. Consult your network administrator if you suspect this is the case.

5. Interpret Error Responses

The Kutt API provides informative error messages in its responses. Pay attention to the HTTP status code and the JSON error payload:

• 400 Bad Request: Indicates issues with your request, such as invalid JSON or missing required parameters. The response body will likely contain details.
• 401 Unauthorized: Typically means your API key is missing or invalid.
• 403 Forbidden: Could indicate insufficient permissions or an expired API key, or that the custom slug you requested is already taken.
• 429 Too Many Requests: You have exceeded the API rate limits. Implement exponential backoff for retries.
• 5xx Server Error: An issue on Kutt's side. If these persist, check the Kutt status page or contact support.

By systematically checking these points, you can often identify and resolve issues with your initial API calls to Kutt.