API Documentation

QuickGo provides a simple REST API for programmatic access. Creating short links through the API requires an API key.

Authentication

Creation requests must include an API key using one of the following methods:

Contact me to get an API key.

Endpoints

POST /api/v1/shorten

Create a shortened URL.

Request Headers

Content-Type: application/json
X-API-Key: your-api-key-here

Request Body

{
  "url": "https://example.com/very/long/url",
  "expires_at": 1907755200,
  "password": "example passphrase",
  "max_visits": 10
}

Only url is required. Optional fields include expires_at (UTC Unix seconds), password, max_visits (positive integer).

Success Response (201 Created)

{
  "original_url": "https://example.com/very/long/url",
  "short_code": "AC3X79",
  "short_url": "https://qkgo.de/AC3X79",
  "edit_token": "qke_โ€ฆ"
}

The response includes an Edit Token once, for consistency with web-created links. It is only for /edit.

Error Responses

Status Code Description
400 Malformed JSON, or an invalid or too-long URL
401 Missing or invalid API key
403 Access denied by the reverse proxy
413 Request body too large
415 Content-Type must be application/json
422 JSON body does not match the expected fields
429 Too many requests. Wait before retrying and use backoff.
500 Internal server error

Error Response Format

Application errors may use the JSON format below. Proxy errors, including 429, may return HTML. Check the status and Content-Type before parsing the body. Honor Retry-After if present.

{
  "error": "Error message description"
}

GET /api/v1/links/{code}

Read a link using the API key that created it.

Request

curl https://qkgo.de/api/v1/links/AC3X79 \
  -H "X-API-Key: your-api-key-here"

Response (200 OK)

{
  "short_code": "AC3X79",
  "original_url": "https://example.com/very/long/url",
  "expires_at": 1907755200,
  "has_password": false,
  "max_visits": 10,
  "visit_count": 2,
  "updated_at": "2030-02-01 12:00:00"
}

PATCH /api/v1/links/{code}

Use the API key that created the link. PATCH accepts url and the optional fields above. Omit fields to keep them. Use null to clear restrictions.

Request

curl -X PATCH https://qkgo.de/api/v1/links/AC3X79 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"url": "https://example.com/new", "expires_at": null}'

Response (200 OK)

{
  "short_code": "AC3X79",
  "original_url": "https://example.com/new",
  "expires_at": null,
  "has_password": false,
  "max_visits": 10,
  "visit_count": 2,
  "updated_at": "2030-02-01 12:05:00"
}

404 means missing or unowned. 410 means revoked.

Example Usage

cURL

curl -X POST https://qkgo.de/api/v1/shorten \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key-here" \
  -d '{"url":"https://example.com/very/long/url","expires_at":1907755200,"password":"example passphrase","max_visits":10}'